diff --git a/.semgrep/rules/security/idor-team-scoped-models.yaml b/.semgrep/rules/security/idor-team-scoped-models.yaml
index 75879d11a5a8..031b70fbc983 100644
--- a/.semgrep/rules/security/idor-team-scoped-models.yaml
+++ b/.semgrep/rules/security/idor-team-scoped-models.yaml
@@ -188,6 +188,9 @@ rules:
|LogsExclusionRule
|LogsMetricRule
|LogsView
+ |Loop
+ |LoopFire
+ |LoopTrigger
|LLMModelConfiguration
|LLMPrompt
|LLMPromptLabel
@@ -493,6 +496,9 @@ rules:
|KnowledgeSource
|Link
|LiveDebuggerBreakpoint
+ |Loop
+ |LoopFire
+ |LoopTrigger
|LLMModelConfiguration
|LLMPrompt
|LLMPromptLabel
diff --git a/frontend/src/layout/navigation-3000/sidepanel/panels/access_control/ResourceAccessControlsV2/accessControlsLogic.ts b/frontend/src/layout/navigation-3000/sidepanel/panels/access_control/ResourceAccessControlsV2/accessControlsLogic.ts
index 8a4b31f85375..d1cb14f50de9 100644
--- a/frontend/src/layout/navigation-3000/sidepanel/panels/access_control/ResourceAccessControlsV2/accessControlsLogic.ts
+++ b/frontend/src/layout/navigation-3000/sidepanel/panels/access_control/ResourceAccessControlsV2/accessControlsLogic.ts
@@ -367,6 +367,7 @@ export interface accessControlsLogicActions {
| 'llm_provider_key'
| 'llm_skill'
| 'logs'
+ | 'loop'
| 'marketing_analytics'
| 'mcp_analytics'
| 'metrics'
@@ -503,6 +504,7 @@ export interface accessControlsLogicMeta {
| 'llm_provider_key'
| 'llm_skill'
| 'logs'
+ | 'loop'
| 'marketing_analytics'
| 'mcp_analytics'
| 'metrics'
@@ -643,6 +645,7 @@ export interface accessControlsLogicMeta {
| 'llm_provider_key'
| 'llm_skill'
| 'logs'
+ | 'loop'
| 'marketing_analytics'
| 'mcp_analytics'
| 'metrics'
@@ -756,6 +759,7 @@ export interface accessControlsLogicMeta {
| 'llm_provider_key'
| 'llm_skill'
| 'logs'
+ | 'loop'
| 'marketing_analytics'
| 'mcp_analytics'
| 'metrics'
diff --git a/frontend/src/layout/navigation-3000/sidepanel/panels/access_control/ResourceAccessControlsV2/groupedAccessControlRuleModalLogic.ts b/frontend/src/layout/navigation-3000/sidepanel/panels/access_control/ResourceAccessControlsV2/groupedAccessControlRuleModalLogic.ts
index cc07ff8cb083..f228bc011c58 100644
--- a/frontend/src/layout/navigation-3000/sidepanel/panels/access_control/ResourceAccessControlsV2/groupedAccessControlRuleModalLogic.ts
+++ b/frontend/src/layout/navigation-3000/sidepanel/panels/access_control/ResourceAccessControlsV2/groupedAccessControlRuleModalLogic.ts
@@ -88,6 +88,7 @@ export interface groupedAccessControlRuleModalLogicValues {
| 'llm_provider_key'
| 'llm_skill'
| 'logs'
+ | 'loop'
| 'marketing_analytics'
| 'mcp_analytics'
| 'metrics'
@@ -205,6 +206,7 @@ export interface groupedAccessControlRuleModalLogicValues {
| 'llm_provider_key'
| 'llm_skill'
| 'logs'
+ | 'loop'
| 'marketing_analytics'
| 'mcp_analytics'
| 'metrics'
@@ -314,6 +316,7 @@ export interface groupedAccessControlRuleModalLogicValues {
| 'llm_provider_key'
| 'llm_skill'
| 'logs'
+ | 'loop'
| 'marketing_analytics'
| 'mcp_analytics'
| 'metrics'
@@ -436,6 +439,7 @@ export interface groupedAccessControlRuleModalLogicValues {
| 'llm_provider_key'
| 'llm_skill'
| 'logs'
+ | 'loop'
| 'marketing_analytics'
| 'mcp_analytics'
| 'metrics'
@@ -558,6 +562,7 @@ export interface groupedAccessControlRuleModalLogicActions {
| 'llm_provider_key'
| 'llm_skill'
| 'logs'
+ | 'loop'
| 'marketing_analytics'
| 'mcp_analytics'
| 'metrics'
@@ -687,6 +692,7 @@ export interface groupedAccessControlRuleModalLogicActions {
| 'llm_provider_key'
| 'llm_skill'
| 'logs'
+ | 'loop'
| 'marketing_analytics'
| 'mcp_analytics'
| 'metrics'
@@ -796,6 +802,7 @@ export interface groupedAccessControlRuleModalLogicActions {
| 'llm_provider_key'
| 'llm_skill'
| 'logs'
+ | 'loop'
| 'marketing_analytics'
| 'mcp_analytics'
| 'metrics'
@@ -944,6 +951,7 @@ export interface groupedAccessControlRuleModalLogicMeta {
| 'llm_provider_key'
| 'llm_skill'
| 'logs'
+ | 'loop'
| 'marketing_analytics'
| 'mcp_analytics'
| 'metrics'
@@ -1055,6 +1063,7 @@ export interface groupedAccessControlRuleModalLogicMeta {
| 'llm_provider_key'
| 'llm_skill'
| 'logs'
+ | 'loop'
| 'marketing_analytics'
| 'mcp_analytics'
| 'metrics'
@@ -1165,6 +1174,7 @@ export interface groupedAccessControlRuleModalLogicMeta {
| 'llm_provider_key'
| 'llm_skill'
| 'logs'
+ | 'loop'
| 'marketing_analytics'
| 'mcp_analytics'
| 'metrics'
@@ -1275,6 +1285,7 @@ export interface groupedAccessControlRuleModalLogicMeta {
| 'llm_provider_key'
| 'llm_skill'
| 'logs'
+ | 'loop'
| 'marketing_analytics'
| 'mcp_analytics'
| 'metrics'
@@ -1386,6 +1397,7 @@ export interface groupedAccessControlRuleModalLogicMeta {
| 'llm_provider_key'
| 'llm_skill'
| 'logs'
+ | 'loop'
| 'marketing_analytics'
| 'mcp_analytics'
| 'metrics'
@@ -1496,6 +1508,7 @@ export interface groupedAccessControlRuleModalLogicMeta {
| 'llm_provider_key'
| 'llm_skill'
| 'logs'
+ | 'loop'
| 'marketing_analytics'
| 'mcp_analytics'
| 'metrics'
@@ -1617,6 +1630,7 @@ export interface groupedAccessControlRuleModalLogicMeta {
| 'llm_provider_key'
| 'llm_skill'
| 'logs'
+ | 'loop'
| 'marketing_analytics'
| 'mcp_analytics'
| 'metrics'
@@ -1727,6 +1741,7 @@ export interface groupedAccessControlRuleModalLogicMeta {
| 'llm_provider_key'
| 'llm_skill'
| 'logs'
+ | 'loop'
| 'marketing_analytics'
| 'mcp_analytics'
| 'metrics'
diff --git a/frontend/src/layout/navigation-3000/sidepanel/panels/access_control/accessControlLogic.ts b/frontend/src/layout/navigation-3000/sidepanel/panels/access_control/accessControlLogic.ts
index ae9e068e7aca..1f96546e9c50 100644
--- a/frontend/src/layout/navigation-3000/sidepanel/panels/access_control/accessControlLogic.ts
+++ b/frontend/src/layout/navigation-3000/sidepanel/panels/access_control/accessControlLogic.ts
@@ -364,6 +364,7 @@ export interface accessControlLogicMeta {
| 'llm_provider_key'
| 'llm_skill'
| 'logs'
+ | 'loop'
| 'marketing_analytics'
| 'mcp_analytics'
| 'metrics'
@@ -577,6 +578,7 @@ export interface accessControlLogicMeta {
| 'llm_provider_key'
| 'llm_skill'
| 'logs'
+ | 'loop'
| 'marketing_analytics'
| 'mcp_analytics'
| 'metrics'
@@ -687,6 +689,7 @@ export interface accessControlLogicMeta {
| 'llm_provider_key'
| 'llm_skill'
| 'logs'
+ | 'loop'
| 'marketing_analytics'
| 'mcp_analytics'
| 'metrics'
diff --git a/frontend/src/lib/agentScopes.generated.ts b/frontend/src/lib/agentScopes.generated.ts
index a8032ecd0153..427f035e3b4a 100644
--- a/frontend/src/lib/agentScopes.generated.ts
+++ b/frontend/src/lib/agentScopes.generated.ts
@@ -79,6 +79,8 @@ export const AGENT_USE_CASE_SCOPES = [
'llm_skill:write',
'logs:read',
'logs:write',
+ 'loop:read',
+ 'loop:write',
'marketing_analytics:read',
'mcp_analytics:read',
'mcp_analytics:write',
diff --git a/frontend/src/lib/scopes.tsx b/frontend/src/lib/scopes.tsx
index 70243338de32..47808e85423a 100644
--- a/frontend/src/lib/scopes.tsx
+++ b/frontend/src/lib/scopes.tsx
@@ -126,6 +126,7 @@ export const API_SCOPES: APIScope[] = [
{ key: 'llm_provider_key', objectName: 'LLM provider key', objectPlural: 'LLM provider keys' },
{ key: 'llm_skill', objectName: 'LLM skill', objectPlural: 'LLM skills' },
{ key: 'logs', objectName: 'Logs', objectPlural: 'logs' },
+ { key: 'loop', objectName: 'Loop', objectPlural: 'loops' },
{ key: 'marketing_analytics', objectName: 'Marketing analytics', objectPlural: 'marketing analytics' },
{ key: 'mcp_analytics', objectName: 'MCP analytics', objectPlural: 'MCP analytics' },
{ key: 'metrics', objectName: 'Metrics', objectPlural: 'metrics' },
@@ -257,6 +258,7 @@ export const PROJECT_SECRET_API_KEY_ALLOWED_API_SCOPE_ACTION = [
'endpoint:read',
'feature_flag:read',
'account:read',
+ 'loop:write',
] as const
export type ProjectSecretAPIKeyAllowedScope = (typeof PROJECT_SECRET_API_KEY_ALLOWED_API_SCOPE_ACTION)[number]
diff --git a/frontend/src/types.ts b/frontend/src/types.ts
index 98006e962f95..acc53cda4729 100644
--- a/frontend/src/types.ts
+++ b/frontend/src/types.ts
@@ -5740,6 +5740,7 @@ export const API_SCOPE_OBJECTS = [
'llm_provider_key',
'llm_skill',
'logs',
+ 'loop',
'marketing_analytics',
'mcp_analytics',
'metrics',
diff --git a/posthog/api/advanced_activity_logs/viewset.py b/posthog/api/advanced_activity_logs/viewset.py
index 6727e27454e9..5228c7feac93 100644
--- a/posthog/api/advanced_activity_logs/viewset.py
+++ b/posthog/api/advanced_activity_logs/viewset.py
@@ -39,6 +39,48 @@
from .utils import get_activity_log_lookback_restriction
+def restrict_loop_activity(queryset: QuerySet[ActivityLog], team_id: int, user) -> QuerySet[ActivityLog]:
+ """Keep personal loops' config out of the team-wide activity feed.
+
+ Loop activity is team-scoped in the log, but a personal loop is owner-only (see
+ products/tasks/docs/LOOPS.md "Access control"). The static visibility manager can't express
+ per-user ownership, so restrict `Loop`-scoped rows to the loops this user may actually see.
+ Lazy import keeps the tasks product off this module's import path.
+ """
+ from products.tasks.backend.facade import loops as loops_facade # noqa: PLC0415
+
+ visible_ids = loops_facade.visible_loop_ids(team_id, user)
+ return queryset.exclude(Q(scope="Loop") & ~Q(item_id__in=visible_ids))
+
+
+def restrict_loop_activity_for_org(queryset: QuerySet[ActivityLog], organization_id, user) -> QuerySet[ActivityLog]:
+ """Org-wide equivalent of `restrict_loop_activity`. The org route has no single `team_id`, so it
+ can't build a per-team allowlist; instead deny other users' personal-loop rows across the org.
+
+ Two filters, both required. The persisted per-row context (`detail.context.visibility` /
+ `created_by_user_id`, snapshotted at log time) is the primary one: `ActivityLog` outlives its
+ loop (project deletion cascades `Loop` rows away while the log keeps plain `team_id` /
+ `organization_id`), so a live-row denylist alone would open another user's deleted personal-loop
+ history to org admins. The live-row denylist stays on top so a currently-personal loop hides ALL
+ its rows, including ones logged back when it was team-visible.
+
+ No object-level loop RBAC here, deliberately: this route is restricted to org admins and owners
+ (`OrganizationActivityLogPermission`), who pass the RBAC precheck for every object, so the
+ filter the team route applies via `visible_loop_ids` would be a no-op on this one."""
+ from products.tasks.backend.facade import loops as loops_facade # noqa: PLC0415
+
+ user_id = getattr(user, "id", None)
+ persisted_personal = Q(scope="Loop") & Q(detail__context__visibility="personal")
+ if user_id is not None:
+ persisted_personal &= ~Q(detail__context__created_by_user_id=str(user_id))
+ queryset = queryset.exclude(persisted_personal)
+
+ hidden_ids = loops_facade.hidden_personal_loop_ids_for_org(organization_id, user)
+ if not hidden_ids:
+ return queryset
+ return queryset.exclude(Q(scope="Loop") & Q(item_id__in=hidden_ids))
+
+
def apply_organization_scoped_filter(
queryset: QuerySet[ActivityLog], include_org_scoped: bool, team_id: int, organization_id
) -> QuerySet[ActivityLog]:
@@ -192,6 +234,7 @@ def safely_get_queryset(self, queryset) -> QuerySet:
queryset = queryset.filter(created_at__gte=lookback_date)
queryset = apply_activity_visibility_restrictions(queryset, self.request.user)
+ queryset = restrict_loop_activity(queryset, self.team_id, self.request.user)
return queryset
@@ -438,6 +481,7 @@ def safely_get_queryset(self, queryset) -> QuerySet:
queryset = queryset.filter(created_at__gte=lookback_date)
queryset = apply_activity_visibility_restrictions(queryset, self.request.user)
+ queryset = restrict_loop_activity(queryset, self.team_id, self.request.user)
return queryset.order_by("-created_at")
@@ -584,6 +628,8 @@ def safely_get_queryset(self, queryset) -> QuerySet:
queryset = queryset.filter(created_at__gte=lookback_date)
queryset = apply_activity_visibility_restrictions(queryset, self.request.user)
+ # Org route: no single team_id (this endpoint is org-nested), so use the org-wide variant.
+ queryset = restrict_loop_activity_for_org(queryset, self.organization.id, self.request.user)
return queryset.order_by("-created_at")
diff --git a/posthog/api/github_callback/installation_events.py b/posthog/api/github_callback/installation_events.py
index 46d85021956b..fd47facaf382 100644
--- a/posthog/api/github_callback/installation_events.py
+++ b/posthog/api/github_callback/installation_events.py
@@ -7,6 +7,10 @@
The handler never calls GitHub's DELETE endpoint — the App is already gone —
which keeps the outbound/inbound pair loop-free.
+
+Before the Integration rows are deleted, any Loop (products/tasks) referencing them is
+auto-paused and flagged for attention, so a disconnected integration never leaves a loop
+silently pointed at a repository it can no longer reach.
"""
from django.http import HttpResponse
@@ -38,6 +42,9 @@ def handle_installation_event(payload: dict) -> HttpResponse:
installation_id = str(installation_id)
+ integrations = list(Integration.objects.filter(kind="github", integration_id=installation_id))
+ _pause_loops_referencing_integrations(integrations, installation_id)
+
team_deleted, _ = Integration.objects.filter(kind="github", integration_id=installation_id).delete()
user_deleted, _ = UserIntegration.objects.filter(kind="github", integration_id=installation_id).delete()
@@ -49,3 +56,25 @@ def handle_installation_event(payload: dict) -> HttpResponse:
)
return HttpResponse(status=200)
+
+
+def _pause_loops_referencing_integrations(integrations: list[Integration], installation_id: str) -> None:
+ """Auto-pause every loop referencing a GitHub integration that's about to be hard-deleted.
+
+ See products/tasks/docs/LOOPS.md "Lifecycle and reconciliation": the App uninstall hard-deletes
+ the Integration row with no downstream hooks, and loop references to it are JSON, so no FK
+ machinery helps. Runs before the delete below and is fully isolated: a loops-side failure must
+ never break the pre-existing Integration/UserIntegration deletion path.
+ """
+ if not integrations:
+ return
+
+ try:
+ from products.tasks.backend.facade.loops import ( # noqa: PLC0415 (keeps the loops/Temporal dependency off this module's import path)
+ pause_loops_referencing_integrations,
+ )
+ except Exception:
+ logger.exception("github_installation_webhook_loop_import_failed", installation_id=installation_id)
+ return
+
+ pause_loops_referencing_integrations(integrations, installation_id)
diff --git a/posthog/email.py b/posthog/email.py
index 39b6b79b8079..5b3ea1c6abb3 100644
--- a/posthog/email.py
+++ b/posthog/email.py
@@ -149,6 +149,7 @@ def is_email_available(with_absolute_urls: bool = False) -> bool:
"integration_access_requested": "70",
"posthog_ai_access_requested": "72",
"wizard_pr_ready": "74",
+ "loop_run_summary": "73", # placeholder id, needs creating in Customer.io
}
diff --git a/posthog/models/activity_logging/activity_log.py b/posthog/models/activity_logging/activity_log.py
index 906e20dd2e6c..9e5edb1829ca 100644
--- a/posthog/models/activity_logging/activity_log.py
+++ b/posthog/models/activity_logging/activity_log.py
@@ -98,6 +98,7 @@
"Metric",
"TableCertification",
"Billing",
+ "Loop",
]
ChangeAction = Literal[
"changed", "created", "deleted", "merged", "split", "exported", "revoked", "logged_in", "logged_out", "copied"
@@ -357,6 +358,12 @@ class Meta:
"consecutive_failures",
"state",
],
+ "Loop": [
+ "last_run_at",
+ "last_run_status",
+ "last_error",
+ "consecutive_failures",
+ ],
"PersonalAPIKey": [
"last_used_at",
],
@@ -439,6 +446,21 @@ class Meta:
"source_insight_query_hash",
"referenced_table_names",
],
+ "Loop": [
+ # FK relations are not JSON-serializable for the change detail (same reason
+ # FeatureFlag/Subscription exclude theirs).
+ "team",
+ "sandbox_environment",
+ # Reverse FKs (LoopTrigger, LoopFire): reading them goes through those models' own
+ # fail-closed TeamScopedManagers with no ambient team scope at signal-handling time.
+ "triggers",
+ "fires",
+ # Run bookkeeping, not user-meaningful config.
+ "last_run_at",
+ "last_run_status",
+ "last_error",
+ "consecutive_failures",
+ ],
"OrganizationDomain": [
"organization",
"scim_provisioned_users",
diff --git a/posthog/models/organization.py b/posthog/models/organization.py
index c87037113d5f..b779ae992256 100644
--- a/posthog/models/organization.py
+++ b/posthog/models/organization.py
@@ -766,6 +766,18 @@ def _sync_if_org_exists():
transaction.on_commit(_sync_if_org_exists)
+@receiver(models.signals.post_delete, sender=OrganizationMembership)
+def pause_loops_on_membership_removal(sender, instance: OrganizationMembership, **kwargs):
+ # A loop run executes with its owner's credentials, so offboarding a member must pause their loops
+ # in that org and cancel in-flight runs. Deferred import keeps loops/Temporal deps off the model
+ # import path (mirrors the User-deactivation hook).
+ from products.tasks.backend.facade.loops import pause_loops_for_removed_member # noqa: PLC0415
+
+ user_id = instance.user_id
+ organization_id = str(instance.organization_id)
+ transaction.on_commit(lambda: pause_loops_for_removed_member(user_id, organization_id))
+
+
@receiver(models.signals.pre_save, sender=OrganizationMembership)
def organization_membership_saved(sender: Any, instance: OrganizationMembership, **kwargs: Any) -> None:
from posthog.event_usage import report_user_organization_membership_level_changed
diff --git a/posthog/models/user.py b/posthog/models/user.py
index fb829fa40902..e6bbcfe850f7 100644
--- a/posthog/models/user.py
+++ b/posthog/models/user.py
@@ -641,3 +641,27 @@ def _revoke_sessions_on_user_deactivation(sender: type[User], instance: User, **
from posthog.session.activity import revoke_other_sessions # noqa: PLC0415 — avoids a circular import
revoke_other_sessions(instance, keep_session_key=None)
+
+
+@receiver(pre_save, sender=User)
+def _pause_loops_on_user_deactivation(sender: type[User], instance: User, **kwargs: object) -> None:
+ """Pause every loop owned by a user when they are deactivated (is_active True->False).
+
+ Loops execute as their owner for GitHub authorship and MCP identity (see
+ products/tasks/docs/LOOPS.md "Lifecycle and reconciliation"); deactivation is often the
+ security response and must not leave a loop still scheduled, or a sandbox still running,
+ under that owner's identity. Deferred to `transaction.on_commit` since pausing a loop's
+ Temporal schedule is an irreversible external side effect.
+ """
+ if instance._state.adding or instance.is_active:
+ return
+ was_active = sender.objects.filter(pk=instance.pk).values_list("is_active", flat=True).first()
+ if not was_active:
+ return
+
+ from products.tasks.backend.facade.loops import ( # noqa: PLC0415 (keeps loops/Temporal deps off the User model import path)
+ pause_loops_for_deactivated_user,
+ )
+
+ user_id = instance.pk
+ transaction.on_commit(lambda: pause_loops_for_deactivated_user(user_id))
diff --git a/posthog/personhog_client/converters.py b/posthog/personhog_client/converters.py
index 94c96f162682..b39bca53d73e 100644
--- a/posthog/personhog_client/converters.py
+++ b/posthog/personhog_client/converters.py
@@ -68,7 +68,8 @@ def proto_person_to_model(
obj = PersonModel(
id=person.id,
- uuid=uuid_mod.UUID(person.uuid) if person.uuid else None, # type: ignore[misc]
+ # unused-ignore: needed under CI's env (ee installed, stricter Person stubs), unused locally.
+ uuid=uuid_mod.UUID(person.uuid) if person.uuid else None, # type: ignore[misc, unused-ignore]
team_id=person.team_id,
properties=json.loads(person.properties) if person.properties else {},
is_identified=person.is_identified,
diff --git a/posthog/scopes.py b/posthog/scopes.py
index c5f9c0f04281..f234caff9ebb 100644
--- a/posthog/scopes.py
+++ b/posthog/scopes.py
@@ -76,6 +76,7 @@
"llm_provider_key",
"llm_skill",
"logs",
+ "loop",
"marketing_analytics",
"mcp_analytics",
"metrics",
@@ -186,6 +187,10 @@
# Gated on a PSAK so the team-wide secret_api_token (readable by any project member)
# can't be used to sidestep per-user account access controls.
("account", "read"),
+ # First write-capable PSAK scope: lets a service credential fire a loop via
+ # `loops/:id/trigger/`. PSAKs are project-wide, so a leaked key can fire any loop
+ # in the project (accepted and documented in products/tasks/docs/LOOPS.md).
+ ("loop", "write"),
]
# Server-side scope assignment string-set constants (see RFC: server-side scope
diff --git a/posthog/settings/web.py b/posthog/settings/web.py
index 4bb26d1fc5f1..df9e1a6b4075 100644
--- a/posthog/settings/web.py
+++ b/posthog/settings/web.py
@@ -649,6 +649,9 @@ def static_varies_origin(headers, path, url):
# choice set (top-level column vs span attribute vs resource attribute).
"SpanPropertyTypeEnum": ["span", "span_attribute", "span_resource_attribute"],
"LogsViewColumnTypeEnum": ["timestamp", "level", "source", "trace_id", "span_id", "message", "custom"],
+ # LoopTriggerWrite.type and LoopPreviewRequest.trigger_type share the same
+ # schedule/github/api choice set — pin them to a single named enum.
+ "LoopTriggerTypeEnum": ["schedule", "github", "api"],
"CustomPropertyDisplayTypeEnum": [
"text",
"number",
diff --git a/posthog/storage/test/test_team_access_cache_signal_handlers.py b/posthog/storage/test/test_team_access_cache_signal_handlers.py
index c74220bb7d3c..9c8653ec6d62 100644
--- a/posthog/storage/test/test_team_access_cache_signal_handlers.py
+++ b/posthog/storage/test/test_team_access_cache_signal_handlers.py
@@ -485,7 +485,12 @@ def test_from_db_sets_original_is_active_for_change_detection(self, mock_on_comm
loaded_user.is_active = False
loaded_user.save()
- mock_on_commit.assert_called_once()
+ # A real save fires every User receiver, and others (loop pausing on deactivation) also
+ # schedule on_commit work; count only this handler's contribution.
+ user_saved_commits = [
+ call for call in mock_on_commit.call_args_list if "user_saved" in call.args[0].__qualname__
+ ]
+ self.assertEqual(len(user_saved_commits), 1)
class TestOrganizationMembershipSavedSignalHandler(TestCase):
diff --git a/posthog/tasks/scheduled.py b/posthog/tasks/scheduled.py
index 6303c6853770..3ec9bbc57473 100644
--- a/posthog/tasks/scheduled.py
+++ b/posthog/tasks/scheduled.py
@@ -102,7 +102,11 @@
prune_old_streamlit_app_versions,
stop_idle_streamlit_sandboxes,
)
-from products.tasks.backend.facade.tasks import refresh_stale_sandbox_custom_images_task
+from products.tasks.backend.facade.tasks import (
+ reconcile_loop_trigger_schedules_task,
+ refresh_stale_sandbox_custom_images_task,
+ sweep_loop_task_retention_task,
+)
from products.web_analytics.backend.achievements.tasks import sweep_web_analytics_achievement_team_tracks
from products.web_analytics.backend.tasks.heatmap_screenshot import report_stuck_heatmap_screenshots
@@ -278,6 +282,23 @@ def setup_periodic_tasks(sender: Celery, **kwargs: Any) -> None:
name="sync pending signals refund credits",
)
+ # Loop task retention sweep - daily at 4:30 AM
+ add_periodic_task_with_expiry(
+ sender,
+ crontab(hour="4", minute="30"),
+ sweep_loop_task_retention_task.s(),
+ name="sweep loop task retention",
+ )
+
+ # Loop trigger schedule reconciliation - every 10 minutes, re-syncs schedules
+ # stranded pending/failed by a transient Temporal outage during create/edit.
+ add_periodic_task_with_expiry(
+ sender,
+ crontab(minute="*/10"),
+ reconcile_loop_trigger_schedules_task.s(),
+ name="reconcile loop trigger schedules",
+ )
+
# Flags cache sync - hourly
sender.add_periodic_task(
crontab(hour="*", minute="15"),
diff --git a/posthog/templates/email/loop_run_summary.html b/posthog/templates/email/loop_run_summary.html
new file mode 100644
index 000000000000..52b80aeb8bf6
--- /dev/null
+++ b/posthog/templates/email/loop_run_summary.html
@@ -0,0 +1,18 @@
+{% extends "email/base.html" %} {% load posthog_assets %} {% load posthog_filters %}
+{% block heading %}{{ event_title }}{% endblock %}
+{% block section %}
+
+ Your loop {{ loop_name }}: {{ event_body }}
+
+{% if run_url %}
+
+
+
+ If the button above doesn't work, paste this link into your browser:
+ {{ run_url }}
+
+
+
+
+
+
Loop created
+
{created}
+
+ You'll find it on the Loops page. Edit, pause, or run it anytime.
+
+
+
+ )
+ }
+
+ const items: { label: string; value: ReactNode }[] = [
+ { label: 'Name', value: data.name?.trim() || 'Not set' },
+ { label: 'Visibility', value: data.visibility === 'team' ? 'Team' : 'Personal' },
+ {
+ label: 'What it does',
+ value: {data.instructions?.trim() || 'No prompt'},
+ },
+ { label: 'Runs', value: describeTriggers(data.triggers) },
+ { label: 'Context', value: describeContext(data.context_target) },
+ { label: 'Repository', value: describeRepository(data.repositories) },
+ { label: 'Model', value: describeModel(data) },
+ { label: 'Opens PRs', value: data.behaviors?.create_prs ? 'Yes' : 'No' },
+ { label: 'Auto-fix PRs', value: describeAutoFix(data.behaviors) },
+ { label: 'Notifications', value: describeNotifications(data.notifications) },
+ ]
+
+ const creating = state?.loading ?? false
+ const createDisabled = creating || !onCreate
+ const create = (): void => {
+ void onCreate?.()
+ }
+
+ return (
+
+
+
+
+
Review this loop
+
Check the details below, then create it.
+
+
+
+ {state.error}
+
+ ) : null}
+
+
+
+
+ )
+}
diff --git a/products/tasks/mcp/apps/index.ts b/products/tasks/mcp/apps/index.ts
new file mode 100644
index 000000000000..1d16d20b291e
--- /dev/null
+++ b/products/tasks/mcp/apps/index.ts
@@ -0,0 +1,12 @@
+export {
+ LoopReviewView,
+ type LoopReviewBehaviors,
+ type LoopReviewContextOutputs,
+ type LoopReviewContextTarget,
+ type LoopReviewData,
+ type LoopReviewNotificationChannel,
+ type LoopReviewRepository,
+ type LoopReviewState,
+ type LoopReviewTrigger,
+ type LoopReviewViewProps,
+} from './LoopReviewView'
diff --git a/products/tasks/mcp/tools.yaml b/products/tasks/mcp/tools.yaml
index 9ef1c31bf642..8a6c5a85082f 100644
--- a/products/tasks/mcp/tools.yaml
+++ b/products/tasks/mcp/tools.yaml
@@ -7,7 +7,11 @@
category: Tasks
feature: tasks
url_prefix: /tasks
-ui_apps: {}
+ui_apps:
+ loops-review:
+ type: custom
+ app_name: PostHog Loop Review
+ description: Review card for a loop before creation, with a Create loop action.
tools:
code-invites-check-access-retrieve:
operation: code_invites_check_access_retrieve
@@ -15,6 +19,138 @@ tools:
code-invites-redeem-create:
operation: code_invites_redeem_create
enabled: false
+ loops-create:
+ operation: loops_create
+ enabled: true
+ scopes:
+ - loop:write
+ annotations:
+ readOnly: false
+ destructive: false
+ idempotent: false
+ title: Create loop
+ description: >
+ Create a new loop: a named, cloud-executed agent automation that runs on a schedule, a GitHub event, or an
+ authenticated API call. Set `instructions` (the prompt delivered to the agent on every run),
+ `runtime_adapter`/`model`/`reasoning_effort`, `repositories` (at most 1, may be empty for a connector-only
+ loop), `visibility` (`personal` or `team`), `behaviors` (PR creation, CI watch, auto-fix) and `triggers`.
+ feature_flag: loops
+ confirmed_action:
+ message: >
+ About to create the loop '{name}', a persistent automation that will run unattended with your GitHub and
+ connector access whenever its triggers fire. Reply 'confirm' to create it.
+ action_label: create loop
+ loops-destroy:
+ operation: loops_destroy
+ enabled: true
+ scopes:
+ - loop:write
+ annotations:
+ readOnly: false
+ destructive: true
+ idempotent: true
+ title: Delete loop
+ description: >
+ Soft-delete a loop and pause every trigger's schedule so it stops firing. Only the loop owner or a project
+ admin can delete a loop.
+ feature_flag: loops
+ loops-list:
+ operation: loops_list
+ enabled: true
+ scopes:
+ - loop:read
+ annotations:
+ readOnly: true
+ destructive: false
+ idempotent: true
+ list: true
+ title: List loops
+ description: >
+ List loops visible to the current user in the project: personal loops the user owns plus every team-visible
+ loop. Returns loop config, trigger summaries, and run bookkeeping (`last_run_at`, `last_run_status`,
+ `consecutive_failures`).
+ feature_flag: loops
+ loops-partial-update:
+ operation: loops_partial_update
+ enabled: true
+ scopes:
+ - loop:write
+ annotations:
+ readOnly: false
+ destructive: false
+ idempotent: false
+ title: Update loop
+ description: >
+ Update an existing loop's config. On a team loop, identity-bearing fields (`instructions`, `repositories`,
+ `connectors`, `behaviors`, `triggers`) are editable only by the current owner: editing them as another
+ member takes ownership and re-validates repositories and connectors against that member's own access.
+ Editing a loop never affects its in-flight or queued runs; every run snapshots its config at fire time.
+ feature_flag: loops
+ loops-preview-create:
+ operation: loops_preview_create
+ enabled: true
+ scopes:
+ - loop:read
+ annotations:
+ readOnly: true
+ destructive: false
+ idempotent: true
+ title: Preview a loop fire
+ description: >
+ Dry-run a loop: render the assembled instructions and trigger context for a sample payload (or a synthetic
+ schedule fire when omitted) without creating a task, run, or any other side effect. Use it to check a loop's
+ prompt before enabling it.
+ feature_flag: loops
+ loops-retrieve:
+ operation: loops_retrieve
+ enabled: true
+ scopes:
+ - loop:read
+ annotations:
+ readOnly: true
+ destructive: false
+ idempotent: true
+ enrich_url: '{id}'
+ title: Get loop
+ description: >
+ Get a specific loop by ID, including its full config (instructions, model, repositories, triggers,
+ behaviors, connectors, notifications) and run bookkeeping.
+ feature_flag: loops
+ loops-run-create:
+ operation: loops_run_create
+ enabled: true
+ scopes:
+ - loop:write
+ annotations:
+ readOnly: false
+ destructive: false
+ idempotent: false
+ title: Manually run a loop
+ description: >
+ Manually fire a loop right now, outside its configured triggers. Creates a fresh task run using the loop's
+ current config snapshot and returns it. Subject to the same usage-gate, overlap policy and rate limits as
+ trigger-fired runs.
+ feature_flag: loops
+ loops-runs-retrieve:
+ operation: loops_runs_retrieve
+ enabled: true
+ scopes:
+ - loop:read
+ annotations:
+ readOnly: true
+ destructive: false
+ idempotent: true
+ enrich_url: '{id}/runs'
+ list: true
+ title: List loop runs
+ description: >
+ List a loop's run history, newest first, cursor-paginated. Each entry carries the run's status, branch,
+ error message and output (including any PR URL), so an agent can check whether a loop's runs succeeded and
+ what they produced.
+ feature_flag: loops
+ loops-trigger-create:
+ operation: loops_trigger_create
+ enabled: false
sandbox-create:
operation: sandbox_create
enabled: false
diff --git a/services/mcp/schema/generated-tool-definitions.json b/services/mcp/schema/generated-tool-definitions.json
index e73faadc0479..b318aad24190 100644
--- a/services/mcp/schema/generated-tool-definitions.json
+++ b/services/mcp/schema/generated-tool-definitions.json
@@ -6088,6 +6088,141 @@
"readOnlyHint": true
}
},
+ "loops-create-execute": {
+ "description": "Step 2 of 2 for create loop. Verifies the confirmation_hash from -prepare and the literal \"confirm\" string typed by the user, then performs the action. ONLY call this after the user has explicitly typed \"confirm\" in chat. Original action: Create a new loop: a named, cloud-executed agent automation that runs on a schedule, a GitHub event, or an authenticated API call. Set `instructions` (the prompt delivered to the agent on every run), `runtime_adapter`/`model`/`reasoning_effort`, `repositories` (at most 1, may be empty for a connector-only loop), `visibility` (`personal` or `team`), `behaviors` (PR creation, CI watch, auto-fix) and `triggers`.",
+ "category": "Tasks",
+ "feature": "tasks",
+ "summary": "Create loop (execute)",
+ "title": "Create loop (execute)",
+ "required_scopes": ["loop:write"],
+ "annotations": {
+ "destructiveHint": false,
+ "idempotentHint": false,
+ "openWorldHint": true,
+ "readOnlyHint": false
+ },
+ "feature_flag": "loops"
+ },
+ "loops-create-prepare": {
+ "description": "Step 1 of 2 for create loop. Validates the arguments and returns a signed confirmation_hash plus a message to surface to the user. The user must reply with the literal word \"confirm\" before you call the matching -execute tool with the hash. Original action: Create a new loop: a named, cloud-executed agent automation that runs on a schedule, a GitHub event, or an authenticated API call. Set `instructions` (the prompt delivered to the agent on every run), `runtime_adapter`/`model`/`reasoning_effort`, `repositories` (at most 1, may be empty for a connector-only loop), `visibility` (`personal` or `team`), `behaviors` (PR creation, CI watch, auto-fix) and `triggers`.",
+ "category": "Tasks",
+ "feature": "tasks",
+ "summary": "Create loop (prepare)",
+ "title": "Create loop (prepare)",
+ "required_scopes": ["loop:write"],
+ "annotations": {
+ "destructiveHint": false,
+ "idempotentHint": true,
+ "openWorldHint": true,
+ "readOnlyHint": true
+ },
+ "feature_flag": "loops"
+ },
+ "loops-destroy": {
+ "description": "Soft-delete a loop and pause every trigger's schedule so it stops firing. Only the loop owner or a project admin can delete a loop.",
+ "category": "Tasks",
+ "feature": "tasks",
+ "summary": "Delete loop",
+ "title": "Delete loop",
+ "required_scopes": ["loop:write"],
+ "annotations": {
+ "destructiveHint": true,
+ "idempotentHint": true,
+ "openWorldHint": true,
+ "readOnlyHint": false
+ },
+ "feature_flag": "loops"
+ },
+ "loops-list": {
+ "description": "List loops visible to the current user in the project: personal loops the user owns plus every team-visible loop. Returns loop config, trigger summaries, and run bookkeeping (`last_run_at`, `last_run_status`, `consecutive_failures`).",
+ "category": "Tasks",
+ "feature": "tasks",
+ "summary": "List loops",
+ "title": "List loops",
+ "required_scopes": ["loop:read"],
+ "annotations": {
+ "destructiveHint": false,
+ "idempotentHint": true,
+ "openWorldHint": true,
+ "readOnlyHint": true
+ },
+ "feature_flag": "loops"
+ },
+ "loops-partial-update": {
+ "description": "Update an existing loop's config. On a team loop, identity-bearing fields (`instructions`, `repositories`, `connectors`, `behaviors`, `triggers`) are editable only by the current owner: editing them as another member takes ownership and re-validates repositories and connectors against that member's own access. Editing a loop never affects its in-flight or queued runs; every run snapshots its config at fire time.",
+ "category": "Tasks",
+ "feature": "tasks",
+ "summary": "Update loop",
+ "title": "Update loop",
+ "required_scopes": ["loop:write"],
+ "annotations": {
+ "destructiveHint": false,
+ "idempotentHint": false,
+ "openWorldHint": true,
+ "readOnlyHint": false
+ },
+ "feature_flag": "loops"
+ },
+ "loops-preview-create": {
+ "description": "Dry-run a loop: render the assembled instructions and trigger context for a sample payload (or a synthetic schedule fire when omitted) without creating a task, run, or any other side effect. Use it to check a loop's prompt before enabling it.",
+ "category": "Tasks",
+ "feature": "tasks",
+ "summary": "Preview a loop fire",
+ "title": "Preview a loop fire",
+ "required_scopes": ["loop:read"],
+ "annotations": {
+ "destructiveHint": false,
+ "idempotentHint": true,
+ "openWorldHint": true,
+ "readOnlyHint": true
+ },
+ "feature_flag": "loops"
+ },
+ "loops-retrieve": {
+ "description": "Get a specific loop by ID, including its full config (instructions, model, repositories, triggers, behaviors, connectors, notifications) and run bookkeeping.",
+ "category": "Tasks",
+ "feature": "tasks",
+ "summary": "Get loop",
+ "title": "Get loop",
+ "required_scopes": ["loop:read"],
+ "annotations": {
+ "destructiveHint": false,
+ "idempotentHint": true,
+ "openWorldHint": true,
+ "readOnlyHint": true
+ },
+ "feature_flag": "loops"
+ },
+ "loops-run-create": {
+ "description": "Manually fire a loop right now, outside its configured triggers. Creates a fresh task run using the loop's current config snapshot and returns it. Subject to the same usage-gate, overlap policy and rate limits as trigger-fired runs.",
+ "category": "Tasks",
+ "feature": "tasks",
+ "summary": "Manually run a loop",
+ "title": "Manually run a loop",
+ "required_scopes": ["loop:write"],
+ "annotations": {
+ "destructiveHint": false,
+ "idempotentHint": false,
+ "openWorldHint": true,
+ "readOnlyHint": false
+ },
+ "feature_flag": "loops"
+ },
+ "loops-runs-retrieve": {
+ "description": "List a loop's run history, newest first, cursor-paginated. Each entry carries the run's status, branch, error message and output (including any PR URL), so an agent can check whether a loop's runs succeeded and what they produced.",
+ "category": "Tasks",
+ "feature": "tasks",
+ "summary": "List loop runs",
+ "title": "List loop runs",
+ "required_scopes": ["loop:read"],
+ "annotations": {
+ "destructiveHint": false,
+ "idempotentHint": true,
+ "openWorldHint": true,
+ "readOnlyHint": true
+ },
+ "feature_flag": "loops"
+ },
"managed-migrations-support-get": {
"description": "Get one batch import (managed migration) job by id, from any PostHog team, including the raw worker `state` and `import_config` blobs. PostHog staff only: the backend requires a staff user AND a personal API key explicitly carrying the `batch_import_support:read` scope (a full-access `*` key is rejected; OAuth sign-in can never grant it).\n\nAdds to the list fields:\n\n- `state`: the worker-owned progress blob, `{\"parts\": [{\"key\", \"current_offset\", \"total_size\"}]}`. A part is done when `current_offset >= total_size`; parts are processed in order, so the first unfinished part is the one in flight. `current_offset` is a byte offset into the DECOMPRESSED part - only meaningful against the exact byte stream it was measured on.\n- `import_config`: the job's source / data format / sink configuration. It references credentials by secret key NAME only; secret values live in an encrypted column that is never returned by any API.\n- `created_by_email`: who started the migration, when known.\n\nTroubleshooting reminders (same semantics as the list tool): `waiting_to_start` = running with no worker lease yet; `lease_expired: true` on a running job = the worker died or the job is about to be re-claimed; a `paused` job keeps its lease and resuming (a Django admin action - this API is read-only) must clear it; `paused` with an invalid-JSON parse error at the resume point usually means the source bytes changed under the committed offset and the in-flight part needs a reset to offset 0 via Django admin's \"Resume + re-import in-flight part\".",
"category": "Managed migrations",
diff --git a/services/mcp/schema/tool-definitions-all.json b/services/mcp/schema/tool-definitions-all.json
index 4c999e65351d..a325d3868da0 100644
--- a/services/mcp/schema/tool-definitions-all.json
+++ b/services/mcp/schema/tool-definitions-all.json
@@ -6537,6 +6537,156 @@
"readOnlyHint": true
}
},
+ "loops-create-execute": {
+ "description": "Step 2 of 2 for create loop. Verifies the confirmation_hash from -prepare and the literal \"confirm\" string typed by the user, then performs the action. ONLY call this after the user has explicitly typed \"confirm\" in chat. Original action: Create a new loop: a named, cloud-executed agent automation that runs on a schedule, a GitHub event, or an authenticated API call. Set `instructions` (the prompt delivered to the agent on every run), `runtime_adapter`/`model`/`reasoning_effort`, `repositories` (at most 1, may be empty for a connector-only loop), `visibility` (`personal` or `team`), `behaviors` (PR creation, CI watch, auto-fix) and `triggers`.",
+ "category": "Tasks",
+ "feature": "tasks",
+ "summary": "Create loop (execute)",
+ "title": "Create loop (execute)",
+ "required_scopes": ["loop:write"],
+ "annotations": {
+ "destructiveHint": false,
+ "idempotentHint": false,
+ "openWorldHint": true,
+ "readOnlyHint": false
+ },
+ "feature_flag": "loops"
+ },
+ "loops-create-prepare": {
+ "description": "Step 1 of 2 for create loop. Validates the arguments and returns a signed confirmation_hash plus a message to surface to the user. The user must reply with the literal word \"confirm\" before you call the matching -execute tool with the hash. Original action: Create a new loop: a named, cloud-executed agent automation that runs on a schedule, a GitHub event, or an authenticated API call. Set `instructions` (the prompt delivered to the agent on every run), `runtime_adapter`/`model`/`reasoning_effort`, `repositories` (at most 1, may be empty for a connector-only loop), `visibility` (`personal` or `team`), `behaviors` (PR creation, CI watch, auto-fix) and `triggers`.",
+ "category": "Tasks",
+ "feature": "tasks",
+ "summary": "Create loop (prepare)",
+ "title": "Create loop (prepare)",
+ "required_scopes": ["loop:write"],
+ "annotations": {
+ "destructiveHint": false,
+ "idempotentHint": true,
+ "openWorldHint": true,
+ "readOnlyHint": true
+ },
+ "feature_flag": "loops"
+ },
+ "loops-destroy": {
+ "description": "Soft-delete a loop and pause every trigger's schedule so it stops firing. Only the loop owner or a project admin can delete a loop.",
+ "category": "Tasks",
+ "feature": "tasks",
+ "summary": "Delete loop",
+ "title": "Delete loop",
+ "required_scopes": ["loop:write"],
+ "annotations": {
+ "destructiveHint": true,
+ "idempotentHint": true,
+ "openWorldHint": true,
+ "readOnlyHint": false
+ },
+ "feature_flag": "loops"
+ },
+ "loops-list": {
+ "description": "List loops visible to the current user in the project: personal loops the user owns plus every team-visible loop. Returns loop config, trigger summaries, and run bookkeeping (`last_run_at`, `last_run_status`, `consecutive_failures`).",
+ "category": "Tasks",
+ "feature": "tasks",
+ "summary": "List loops",
+ "title": "List loops",
+ "required_scopes": ["loop:read"],
+ "annotations": {
+ "destructiveHint": false,
+ "idempotentHint": true,
+ "openWorldHint": true,
+ "readOnlyHint": true
+ },
+ "feature_flag": "loops"
+ },
+ "loops-partial-update": {
+ "description": "Update an existing loop's config. On a team loop, identity-bearing fields (`instructions`, `repositories`, `connectors`, `behaviors`, `triggers`) are editable only by the current owner: editing them as another member takes ownership and re-validates repositories and connectors against that member's own access. Editing a loop never affects its in-flight or queued runs; every run snapshots its config at fire time.",
+ "category": "Tasks",
+ "feature": "tasks",
+ "summary": "Update loop",
+ "title": "Update loop",
+ "required_scopes": ["loop:write"],
+ "annotations": {
+ "destructiveHint": false,
+ "idempotentHint": false,
+ "openWorldHint": true,
+ "readOnlyHint": false
+ },
+ "feature_flag": "loops"
+ },
+ "loops-preview-create": {
+ "description": "Dry-run a loop: render the assembled instructions and trigger context for a sample payload (or a synthetic schedule fire when omitted) without creating a task, run, or any other side effect. Use it to check a loop's prompt before enabling it.",
+ "category": "Tasks",
+ "feature": "tasks",
+ "summary": "Preview a loop fire",
+ "title": "Preview a loop fire",
+ "required_scopes": ["loop:read"],
+ "annotations": {
+ "destructiveHint": false,
+ "idempotentHint": true,
+ "openWorldHint": true,
+ "readOnlyHint": true
+ },
+ "feature_flag": "loops"
+ },
+ "loops-retrieve": {
+ "description": "Get a specific loop by ID, including its full config (instructions, model, repositories, triggers, behaviors, connectors, notifications) and run bookkeeping.",
+ "category": "Tasks",
+ "feature": "tasks",
+ "summary": "Get loop",
+ "title": "Get loop",
+ "required_scopes": ["loop:read"],
+ "annotations": {
+ "destructiveHint": false,
+ "idempotentHint": true,
+ "openWorldHint": true,
+ "readOnlyHint": true
+ },
+ "feature_flag": "loops"
+ },
+ "loops-review": {
+ "description": "Show the user an interactive review card for a loop that is about to be created, then let them create it. Call this once you have gathered the loop's details, passing the SAME arguments you would pass to loops-create (name, instructions, runtime_adapter, triggers, behaviors, notifications, context_target, etc.). This renders a card summarizing the loop with a 'Create loop' button. Do NOT call loops-create yourself — the card's button creates the loop after the user confirms.",
+ "category": "Tasks",
+ "feature": "tasks",
+ "feature_flag": "loops",
+ "summary": "Review a loop with the user before creating it.",
+ "title": "Review loop before creating",
+ "required_scopes": ["loop:write"],
+ "annotations": {
+ "destructiveHint": false,
+ "idempotentHint": true,
+ "openWorldHint": false,
+ "readOnlyHint": true
+ }
+ },
+ "loops-run-create": {
+ "description": "Manually fire a loop right now, outside its configured triggers. Creates a fresh task run using the loop's current config snapshot and returns it. Subject to the same usage-gate, overlap policy and rate limits as trigger-fired runs.",
+ "category": "Tasks",
+ "feature": "tasks",
+ "summary": "Manually run a loop",
+ "title": "Manually run a loop",
+ "required_scopes": ["loop:write"],
+ "annotations": {
+ "destructiveHint": false,
+ "idempotentHint": false,
+ "openWorldHint": true,
+ "readOnlyHint": false
+ },
+ "feature_flag": "loops"
+ },
+ "loops-runs-retrieve": {
+ "description": "List a loop's run history, newest first, cursor-paginated. Each entry carries the run's status, branch, error message and output (including any PR URL), so an agent can check whether a loop's runs succeeded and what they produced.",
+ "category": "Tasks",
+ "feature": "tasks",
+ "summary": "List loop runs",
+ "title": "List loop runs",
+ "required_scopes": ["loop:read"],
+ "annotations": {
+ "destructiveHint": false,
+ "idempotentHint": true,
+ "openWorldHint": true,
+ "readOnlyHint": true
+ },
+ "feature_flag": "loops"
+ },
"managed-migrations-support-get": {
"description": "Get one batch import (managed migration) job by id, from any PostHog team, including the raw worker `state` and `import_config` blobs. PostHog staff only: the backend requires a staff user AND a personal API key explicitly carrying the `batch_import_support:read` scope (a full-access `*` key is rejected; OAuth sign-in can never grant it).\n\nAdds to the list fields:\n\n- `state`: the worker-owned progress blob, `{\"parts\": [{\"key\", \"current_offset\", \"total_size\"}]}`. A part is done when `current_offset >= total_size`; parts are processed in order, so the first unfinished part is the one in flight. `current_offset` is a byte offset into the DECOMPRESSED part - only meaningful against the exact byte stream it was measured on.\n- `import_config`: the job's source / data format / sink configuration. It references credentials by secret key NAME only; secret values live in an encrypted column that is never returned by any API.\n- `created_by_email`: who started the migration, when known.\n\nTroubleshooting reminders (same semantics as the list tool): `waiting_to_start` = running with no worker lease yet; `lease_expired: true` on a running job = the worker died or the job is about to be re-claimed; a `paused` job keeps its lease and resuming (a Django admin action - this API is read-only) must clear it; `paused` with an invalid-JSON parse error at the resume point usually means the source bytes changed under the committed offset and the in-flight part needs a reset to offset 0 via Django admin's \"Resume + re-import in-flight part\".",
"category": "Managed migrations",
diff --git a/services/mcp/schema/tool-definitions.json b/services/mcp/schema/tool-definitions.json
index cc1f021c8d5d..744c9ec0bd23 100644
--- a/services/mcp/schema/tool-definitions.json
+++ b/services/mcp/schema/tool-definitions.json
@@ -547,6 +547,21 @@
"readOnlyHint": true
}
},
+ "loops-review": {
+ "description": "Show the user an interactive review card for a loop that is about to be created, then let them create it. Call this once you have gathered the loop's details, passing the SAME arguments you would pass to loops-create (name, instructions, runtime_adapter, triggers, behaviors, notifications, context_target, etc.). This renders a card summarizing the loop with a 'Create loop' button. Do NOT call loops-create yourself — the card's button creates the loop after the user confirms.",
+ "category": "Tasks",
+ "feature": "tasks",
+ "feature_flag": "loops",
+ "summary": "Review a loop with the user before creating it.",
+ "title": "Review loop before creating",
+ "required_scopes": ["loop:write"],
+ "annotations": {
+ "destructiveHint": false,
+ "idempotentHint": true,
+ "openWorldHint": false,
+ "readOnlyHint": true
+ }
+ },
"external-data-sources-db-schema": {
"description": "Validate credentials against a remote source and return the list of tables available to sync (works for database sources like Postgres/MySQL and SaaS sources like Stripe/Hubspot alike). Pass source_type and credential fields in the payload object. Each table entry includes: table name, incremental_available, append_available, cdc_available, supports_webhooks, detected_primary_keys, available_columns (name/type/nullable), rows estimate, and incremental_fields (candidate timestamp/integer columns for incremental sync). Use this BEFORE external-data-sources-create so the user can pick a sync_type per table. Returns 400 with a message if credentials are invalid.",
"category": "Data warehouse",
diff --git a/services/mcp/src/api/generated.ts b/services/mcp/src/api/generated.ts
index 7ec6d936eb70..657072869314 100644
--- a/services/mcp/src/api/generated.ts
+++ b/services/mcp/src/api/generated.ts
@@ -15006,10 +15006,10 @@ export namespace Schemas {
* * `private` - Private (only visible to creator)
* * `shared` - Shared with team
*/
- export type VisibilityEnum = typeof VisibilityEnum[keyof typeof VisibilityEnum];
+ export type ColumnConfigurationVisibilityEnum = typeof ColumnConfigurationVisibilityEnum[keyof typeof ColumnConfigurationVisibilityEnum];
- export const VisibilityEnum = {
+ export const ColumnConfigurationVisibilityEnum = {
Private: 'private',
Shared: 'shared',
} as const;
@@ -15030,7 +15030,7 @@ export namespace Schemas {
order_by?: string[] | null;
/** Product-specific view state that does not fit the columnar fields (e.g. Customer analytics overview tiles and column display). */
properties?: unknown;
- visibility?: VisibilityEnum;
+ visibility?: ColumnConfigurationVisibilityEnum;
/** @nullable */
readonly created_by: number | null;
readonly created_at: string;
@@ -24575,6 +24575,22 @@ export namespace Schemas {
AiTrace: '$ai_trace',
} as const;
+ /**
+ * * `run_completed` - run_completed
+ * * `run_failed` - run_failed
+ * * `pr_created` - pr_created
+ * * `needs_attention` - needs_attention
+ */
+ export type EventsEnum = typeof EventsEnum[keyof typeof EventsEnum];
+
+
+ export const EventsEnum = {
+ RunCompleted: 'run_completed',
+ RunFailed: 'run_failed',
+ PrCreated: 'pr_created',
+ NeedsAttention: 'needs_attention',
+ } as const;
+
export interface ExecuteTestClusterRequest {
/**
* ClickHouse SQL to run against the test cluster.
@@ -35305,6 +35321,452 @@ export namespace Schemas {
readonly updated_at: string | null;
}
+ export interface LoopBehaviors {
+ /** Whether the agent may push branches and open PRs. False makes this a report-only loop. */
+ create_prs?: boolean;
+ /** Whether to watch CI on loop-created PRs and report status. */
+ watch_ci?: boolean;
+ /** Whether to automatically address review comments on loop-created PRs. */
+ fix_review_comments?: boolean;
+ /**
+ * Ceiling on automatic CI/review-comment fix iterations, capped at 10.
+ * @minimum 0
+ * @maximum 10
+ */
+ max_fix_iterations?: number;
+ }
+
+ export interface LoopBehaviorsDTO {
+ create_prs?: boolean;
+ watch_ci?: boolean;
+ fix_review_comments?: boolean;
+ max_fix_iterations?: number;
+ }
+
+ /**
+ * * `read_only` - read_only
+ * * `full` - full
+ */
+ export type PosthogMcpScopesEnum = typeof PosthogMcpScopesEnum[keyof typeof PosthogMcpScopesEnum];
+
+
+ export const PosthogMcpScopesEnum = {
+ ReadOnly: 'read_only',
+ Full: 'full',
+ } as const;
+
+ export interface LoopConnectors {
+ /** MCP Store installation ids (Slack, Linear, etc.) available to this loop's runs. */
+ mcp_installation_ids?: string[];
+ /** Scope of the PostHog MCP access injected into this loop's runs.
+ *
+ * * `read_only` - read_only
+ * * `full` - full */
+ posthog_mcp_scopes?: PosthogMcpScopesEnum;
+ }
+
+ export interface LoopConnectorsDTO {
+ mcp_installation_ids?: string[];
+ posthog_mcp_scopes?: string;
+ }
+
+ export interface LoopContextOutputsDTO {
+ post_to_feed?: boolean;
+ update_context?: boolean;
+ /** @nullable */
+ canvas_id?: string | null;
+ }
+
+ export interface LoopContextOutputsWrite {
+ /** Whether each run is filed into the context's feed as a card (sets the run's channel). */
+ post_to_feed?: boolean;
+ /** Whether each run reads and republishes the context's context.md to reflect the latest state. */
+ update_context?: boolean;
+ /**
+ * Id of a canvas in this context the loop keeps up to date each run, or null to maintain none.
+ * @nullable
+ */
+ canvas_id?: string | null;
+ }
+
+ export interface LoopContextTargetDTO {
+ /** What the loop maintains in this context each run. */
+ outputs: LoopContextOutputsDTO;
+ folder_id: string;
+ name: string;
+ }
+
+ export interface LoopContextTargetWrite {
+ /** Desktop folder id of the context this loop is attached to. */
+ folder_id: string;
+ /**
+ * Context (channel) name, used to file runs into its feed.
+ * @maxLength 128
+ */
+ name: string;
+ /** What the loop maintains in this context each run. */
+ outputs?: LoopContextOutputsWrite;
+ }
+
+ export interface LoopRepositoryEntryDTO {
+ github_integration_id: number;
+ full_name: string;
+ }
+
+ export type LoopNotificationChannelDTOParams = { [key: string]: unknown };
+
+ export interface LoopNotificationChannelDTO {
+ enabled?: boolean;
+ events?: string[];
+ params?: LoopNotificationChannelDTOParams;
+ }
+
+ export interface LoopNotificationsDTO {
+ push: LoopNotificationChannelDTO;
+ email: LoopNotificationChannelDTO;
+ slack: LoopNotificationChannelDTO;
+ }
+
+ export type LoopTriggerDTOConfig = { [key: string]: unknown };
+
+ /**
+ * Read response for a single loop trigger.
+ */
+ export interface LoopTriggerDTO {
+ id: string;
+ loop_id: string;
+ type: string;
+ enabled: boolean;
+ config: LoopTriggerDTOConfig;
+ /** @nullable */
+ schedule_sync_status: string | null;
+ /** @nullable */
+ last_fired_at: string | null;
+ created_at: string;
+ updated_at: string;
+ }
+
+ /**
+ * Detail/create/update response for a loop, including its triggers.
+ */
+ export interface LoopDTO {
+ id: string;
+ team_id: number;
+ /** @nullable */
+ created_by_id: number | null;
+ name: string;
+ description: string;
+ visibility: string;
+ instructions: string;
+ runtime_adapter: string;
+ model: string;
+ /** @nullable */
+ reasoning_effort: string | null;
+ /** Repositories this loop operates on. */
+ repositories: LoopRepositoryEntryDTO[];
+ /** @nullable */
+ sandbox_environment_id: string | null;
+ enabled: boolean;
+ /** @nullable */
+ disabled_reason: string | null;
+ overlap_policy: string;
+ /** PR / CI-follow-up behavior configuration. */
+ behaviors: LoopBehaviorsDTO;
+ /** MCP connector configuration for this loop's runs. */
+ connectors: LoopConnectorsDTO;
+ /** Per-channel notification configuration. */
+ notifications: LoopNotificationsDTO;
+ /** Context this loop is attached to, or null when unattached. */
+ context_target?: LoopContextTargetDTO | null;
+ internal: boolean;
+ origin_product: string;
+ /** @nullable */
+ last_run_at: string | null;
+ /** @nullable */
+ last_run_status: string | null;
+ /** @nullable */
+ last_error: string | null;
+ consecutive_failures: number;
+ created_at: string;
+ updated_at: string;
+ /** Triggers attached to this loop. */
+ triggers: LoopTriggerDTO[];
+ }
+
+ /**
+ * * `created` - created
+ * * `deduped` - deduped
+ * * `overlap_skipped` - overlap_skipped
+ * * `rate_capped` - rate_capped
+ * * `team_rate_capped` - team_rate_capped
+ * * `disabled` - disabled
+ * * `gate_blocked` - gate_blocked
+ * * `owner_inactive` - owner_inactive
+ * * `owner_changed` - owner_changed
+ */
+ export type LoopFireResultReasonEnum = typeof LoopFireResultReasonEnum[keyof typeof LoopFireResultReasonEnum];
+
+
+ export const LoopFireResultReasonEnum = {
+ Created: 'created',
+ Deduped: 'deduped',
+ OverlapSkipped: 'overlap_skipped',
+ RateCapped: 'rate_capped',
+ TeamRateCapped: 'team_rate_capped',
+ Disabled: 'disabled',
+ GateBlocked: 'gate_blocked',
+ OwnerInactive: 'owner_inactive',
+ OwnerChanged: 'owner_changed',
+ } as const;
+
+ /**
+ * Response for a manual (`run/`) or external (`trigger/`) fire.
+ */
+ export interface LoopFireResult {
+ created: boolean;
+ /** Outcome of the fire attempt.
+ *
+ * * `created` - created
+ * * `deduped` - deduped
+ * * `overlap_skipped` - overlap_skipped
+ * * `rate_capped` - rate_capped
+ * * `team_rate_capped` - team_rate_capped
+ * * `disabled` - disabled
+ * * `gate_blocked` - gate_blocked
+ * * `owner_inactive` - owner_inactive
+ * * `owner_changed` - owner_changed */
+ reason: LoopFireResultReasonEnum;
+ /**
+ * Id of the created task, when `created` is true.
+ * @nullable
+ */
+ task_id: string | null;
+ /**
+ * Id of the created task run, when `created` is true.
+ * @nullable
+ */
+ task_run_id: string | null;
+ }
+
+ /**
+ * Channel-specific parameters, e.g. Slack's `integration_id` and `channel`.
+ */
+ export type LoopNotificationChannelParams = { [key: string]: unknown };
+
+ export interface LoopNotificationChannel {
+ /** Whether this channel is active. */
+ enabled?: boolean;
+ /** Event kinds this channel notifies on. One or more of: run_completed, run_failed, pr_created, needs_attention. */
+ events?: EventsEnum[];
+ /** Channel-specific parameters, e.g. Slack's `integration_id` and `channel`. */
+ params?: LoopNotificationChannelParams;
+ }
+
+ export interface LoopNotifications {
+ /** Push notification settings. */
+ push?: LoopNotificationChannel;
+ /** Email notification settings. */
+ email?: LoopNotificationChannel;
+ /** Slack notification settings. */
+ slack?: LoopNotificationChannel;
+ }
+
+ export interface LoopPreviewDTO {
+ instructions: string;
+ trigger_type: string;
+ trigger_context: string;
+ }
+
+ /**
+ * * `schedule` - schedule
+ * * `github` - github
+ * * `api` - api
+ */
+ export type LoopTriggerTypeEnum = typeof LoopTriggerTypeEnum[keyof typeof LoopTriggerTypeEnum];
+
+
+ export const LoopTriggerTypeEnum = {
+ Schedule: 'schedule',
+ Github: 'github',
+ Api: 'api',
+ } as const;
+
+ export interface LoopPreviewRequest {
+ /** Trigger type to simulate. Defaults to a synthetic schedule fire.
+ *
+ * * `schedule` - schedule
+ * * `github` - github
+ * * `api` - api */
+ trigger_type?: LoopTriggerTypeEnum;
+ /** Sample trigger payload, e.g. a GitHub webhook body or an API trigger body, to render into context. */
+ payload?: unknown;
+ }
+
+ export interface LoopRepositoryEntry {
+ /** GitHub integration id this repository is accessed through. */
+ github_integration_id: number;
+ /**
+ * Repository in `organization/repo` format, e.g. `posthog/posthog`.
+ * @maxLength 255
+ */
+ full_name: string;
+ }
+
+ /**
+ * @nullable
+ */
+ export type LoopRunDTOOutput = { [key: string]: unknown } | null;
+
+ /**
+ * A single entry in a loop's run history.
+ */
+ export interface LoopRunDTO {
+ id: string;
+ task_id: string;
+ /** @nullable */
+ loop_trigger_id: string | null;
+ status: string;
+ environment: string;
+ /** @nullable */
+ branch: string | null;
+ /** @nullable */
+ error_message: string | null;
+ /** @nullable */
+ output: LoopRunDTOOutput;
+ created_at: string;
+ /** @nullable */
+ completed_at: string | null;
+ }
+
+ export interface LoopRunPage {
+ /** Run history entries, newest first. */
+ results: LoopRunDTO[];
+ /**
+ * Opaque cursor for the next page, or null when there are no more results.
+ * @nullable
+ */
+ next_cursor: string | null;
+ }
+
+ export interface LoopTriggerWrite {
+ /** Existing trigger id to update in place. Omit to create a new trigger. */
+ id?: string;
+ /** Trigger type: `schedule` (cron or one-time), `github` (repo webhook events), or `api` (POST to `trigger/`).
+ *
+ * * `schedule` - schedule
+ * * `github` - github
+ * * `api` - api */
+ type: LoopTriggerTypeEnum;
+ /** Whether this trigger is active. Disabling pauses only this trigger. */
+ enabled?: boolean;
+ /** Trigger configuration, shape validated per `type`: schedule takes `{cron_expression, timezone}` or `{run_at}` for a one-time run; github takes `{github_integration_id, repository, events, filters}`; api takes no config. */
+ config?: unknown;
+ }
+
+ /**
+ * * `personal` - personal
+ * * `team` - team
+ */
+ export type LoopWriteVisibilityEnum = typeof LoopWriteVisibilityEnum[keyof typeof LoopWriteVisibilityEnum];
+
+
+ export const LoopWriteVisibilityEnum = {
+ Personal: 'personal',
+ Team: 'team',
+ } as const;
+
+ /**
+ * * `claude` - claude
+ * * `codex` - codex
+ */
+ export type RuntimeAdapterEnum = typeof RuntimeAdapterEnum[keyof typeof RuntimeAdapterEnum];
+
+
+ export const RuntimeAdapterEnum = {
+ Claude: 'claude',
+ Codex: 'codex',
+ } as const;
+
+ /**
+ * * `skip` - skip
+ * * `allow` - allow
+ * * `cancel_previous` - cancel_previous
+ */
+ export type OverlapPolicyEnum = typeof OverlapPolicyEnum[keyof typeof OverlapPolicyEnum];
+
+
+ export const OverlapPolicyEnum = {
+ Skip: 'skip',
+ Allow: 'allow',
+ CancelPrevious: 'cancel_previous',
+ } as const;
+
+ /**
+ * Request body for creating or updating a loop. Field required/default semantics match
+ * the `Loop` model; partial updates only touch keys present in the payload.
+ */
+ export interface LoopWrite {
+ /**
+ * Display name for the loop.
+ * @maxLength 400
+ */
+ name: string;
+ /** Free-form description of what this loop does. */
+ description?: string;
+ /** On a team loop, claim ownership as part of this update so you can edit identity-bearing config (instructions, model, triggers, ...) that only the owner may change. Ignored on personal loops and on create. */
+ take_ownership?: boolean;
+ /** `personal` (owner-only) or `team` (visible and fireable by any team member).
+ *
+ * * `personal` - personal
+ * * `team` - team */
+ visibility?: LoopWriteVisibilityEnum;
+ /** The prompt delivered to the agent on every run. */
+ instructions: string;
+ /** Runtime adapter: 'claude' or 'codex'.
+ *
+ * * `claude` - claude
+ * * `codex` - codex */
+ runtime_adapter: RuntimeAdapterEnum;
+ /** LLM model identifier, validated against `runtime_adapter`'s catalog. Leave blank to let PostHog pick a sensible default at run time. */
+ model?: string;
+ /** Reasoning effort, validated against `runtime_adapter`/`model`'s supported set.
+ *
+ * * `low` - low
+ * * `medium` - medium
+ * * `high` - high
+ * * `xhigh` - xhigh
+ * * `max` - max */
+ reasoning_effort?: ReasoningEffortEnum | null;
+ /**
+ * Repositories this loop operates on, ordered. Capped at 1 until multi-repo execution ships. May be empty for report-only loops.
+ * @maxItems 1
+ */
+ repositories?: LoopRepositoryEntry[];
+ /**
+ * Sandbox environment carrying encrypted env vars and the network allowlist into every run.
+ * @nullable
+ */
+ sandbox_environment?: string | null;
+ /** Whether the loop's triggers are active. Pausing disables all triggers. */
+ enabled?: boolean;
+ /** What happens when a trigger fires while a run is already active: 'skip', 'allow', or 'cancel_previous'.
+ *
+ * * `skip` - skip
+ * * `allow` - allow
+ * * `cancel_previous` - cancel_previous */
+ overlap_policy?: OverlapPolicyEnum;
+ /** PR / CI-follow-up behavior configuration. */
+ behaviors?: LoopBehaviors;
+ /** MCP connector configuration for this loop's runs. */
+ connectors?: LoopConnectors;
+ /** Per-channel notification configuration. */
+ notifications?: LoopNotifications;
+ /** Context (channel) this loop is attached to, or null to detach. Drives feed placement and the context.md / canvas it keeps up to date. */
+ context_target?: LoopContextTargetWrite | null;
+ /** Full desired trigger list, id-stable: entries with a matching `id` are updated in place, entries without one are created, and existing triggers absent from this list are deleted. Omit the field entirely to leave triggers untouched. At most 25 triggers per loop. */
+ triggers?: LoopTriggerWrite[];
+ }
+
export interface MCPActivityClientRow {
/** Agent client name ($mcp_client_name). Empty when the SDK did not capture it. */
readonly client: string;
@@ -37540,6 +38002,7 @@ export namespace Schemas {
* * `hogdesk` - HogDesk
* * `review_hog` - ReviewHog
* * `image_builder` - Image Builder
+ * * `loop` - Loop
*/
export type OriginProductEnum = typeof OriginProductEnum[keyof typeof OriginProductEnum];
@@ -37561,6 +38024,7 @@ export namespace Schemas {
Hogdesk: 'hogdesk',
ReviewHog: 'review_hog',
ImageBuilder: 'image_builder',
+ Loop: 'loop',
} as const;
/**
@@ -38743,6 +39207,19 @@ export namespace Schemas {
results: LogsView[];
}
+ export interface PaginatedLoopDTOList {
+ count: number;
+ /** @nullable */
+ next?: string | null;
+ /** @nullable */
+ previous?: string | null;
+ results: LoopDTO[];
+ /** Hard cap on non-deleted loops per project. Creating a loop beyond this returns a 429 with `error: loop_safety_limit`. Authoritative — read this rather than assuming a value. */
+ max_loops_per_team?: number;
+ /** Current number of non-deleted, user-facing loops in this project, counted against `max_loops_per_team`. At or above the cap, creation is blocked. */
+ total_loop_count?: number;
+ }
+
export interface PaginatedMCPAnalyticsSubmissionList {
count: number;
/** @nullable */
@@ -41708,18 +42185,6 @@ export namespace Schemas {
results: TaskAutomationDTO[];
}
- /**
- * * `claude` - claude
- * * `codex` - codex
- */
- export type RuntimeAdapterEnum = typeof RuntimeAdapterEnum[keyof typeof RuntimeAdapterEnum];
-
-
- export const RuntimeAdapterEnum = {
- Claude: 'claude',
- Codex: 'codex',
- } as const;
-
/**
* * `anthropic` - anthropic
* * `openai` - openai
@@ -42841,10 +43306,10 @@ export namespace Schemas {
* * `schedule` - Schedule
* * `threshold` - Threshold
*/
- export type TriggerTypeEnum = typeof TriggerTypeEnum[keyof typeof TriggerTypeEnum];
+ export type VisionActionTriggerTypeEnum = typeof VisionActionTriggerTypeEnum[keyof typeof VisionActionTriggerTypeEnum];
- export const TriggerTypeEnum = {
+ export const VisionActionTriggerTypeEnum = {
Schedule: 'schedule',
Threshold: 'threshold',
} as const;
@@ -42932,7 +43397,7 @@ export namespace Schemas {
*
* * `schedule` - Schedule
* * `threshold` - Threshold */
- trigger_type?: TriggerTypeEnum;
+ trigger_type?: VisionActionTriggerTypeEnum;
/** What the action produces. MVP supports 'group_summary' only.
*
* * `group_summary` - Group summary
@@ -43856,7 +44321,7 @@ export namespace Schemas {
order_by?: string[] | null;
/** Product-specific view state that does not fit the columnar fields (e.g. Customer analytics overview tiles and column display). */
properties?: unknown;
- visibility?: VisibilityEnum;
+ visibility?: ColumnConfigurationVisibilityEnum;
/** @nullable */
readonly created_by?: number | null;
readonly created_at?: string;
@@ -46620,6 +47085,72 @@ export namespace Schemas {
readonly updated_at?: string | null;
}
+ /**
+ * Request body for creating or updating a loop. Field required/default semantics match
+ * the `Loop` model; partial updates only touch keys present in the payload.
+ */
+ export interface PatchedLoopWrite {
+ /**
+ * Display name for the loop.
+ * @maxLength 400
+ */
+ name?: string;
+ /** Free-form description of what this loop does. */
+ description?: string;
+ /** On a team loop, claim ownership as part of this update so you can edit identity-bearing config (instructions, model, triggers, ...) that only the owner may change. Ignored on personal loops and on create. */
+ take_ownership?: boolean;
+ /** `personal` (owner-only) or `team` (visible and fireable by any team member).
+ *
+ * * `personal` - personal
+ * * `team` - team */
+ visibility?: LoopWriteVisibilityEnum;
+ /** The prompt delivered to the agent on every run. */
+ instructions?: string;
+ /** Runtime adapter: 'claude' or 'codex'.
+ *
+ * * `claude` - claude
+ * * `codex` - codex */
+ runtime_adapter?: RuntimeAdapterEnum;
+ /** LLM model identifier, validated against `runtime_adapter`'s catalog. Leave blank to let PostHog pick a sensible default at run time. */
+ model?: string;
+ /** Reasoning effort, validated against `runtime_adapter`/`model`'s supported set.
+ *
+ * * `low` - low
+ * * `medium` - medium
+ * * `high` - high
+ * * `xhigh` - xhigh
+ * * `max` - max */
+ reasoning_effort?: ReasoningEffortEnum | null;
+ /**
+ * Repositories this loop operates on, ordered. Capped at 1 until multi-repo execution ships. May be empty for report-only loops.
+ * @maxItems 1
+ */
+ repositories?: LoopRepositoryEntry[];
+ /**
+ * Sandbox environment carrying encrypted env vars and the network allowlist into every run.
+ * @nullable
+ */
+ sandbox_environment?: string | null;
+ /** Whether the loop's triggers are active. Pausing disables all triggers. */
+ enabled?: boolean;
+ /** What happens when a trigger fires while a run is already active: 'skip', 'allow', or 'cancel_previous'.
+ *
+ * * `skip` - skip
+ * * `allow` - allow
+ * * `cancel_previous` - cancel_previous */
+ overlap_policy?: OverlapPolicyEnum;
+ /** PR / CI-follow-up behavior configuration. */
+ behaviors?: LoopBehaviors;
+ /** MCP connector configuration for this loop's runs. */
+ connectors?: LoopConnectors;
+ /** Per-channel notification configuration. */
+ notifications?: LoopNotifications;
+ /** Context (channel) this loop is attached to, or null to detach. Drives feed placement and the context.md / canvas it keeps up to date. */
+ context_target?: LoopContextTargetWrite | null;
+ /** Full desired trigger list, id-stable: entries with a matching `id` are updated in place, entries without one are created, and existing triggers absent from this list are deleted. Omit the field entirely to leave triggers untouched. At most 25 triggers per loop. */
+ triggers?: LoopTriggerWrite[];
+ }
+
export interface PatchedMCPServerInstallationUpdate {
display_name?: string;
description?: string;
@@ -49689,7 +50220,8 @@ export namespace Schemas {
* * `support_reply` - Support Reply
* * `hogdesk` - HogDesk
* * `review_hog` - ReviewHog
- * * `image_builder` - Image Builder */
+ * * `image_builder` - Image Builder
+ * * `loop` - Loop */
origin_product?: OriginProductEnum;
/**
* Target GitHub repository in `organization/repo` format (e.g. `posthog/posthog-js`).
@@ -50458,7 +50990,7 @@ export namespace Schemas {
*
* * `schedule` - Schedule
* * `threshold` - Threshold */
- trigger_type?: TriggerTypeEnum;
+ trigger_type?: VisionActionTriggerTypeEnum;
/** What the action produces. MVP supports 'group_summary' only.
*
* * `group_summary` - Group summary
@@ -62623,7 +63155,8 @@ export namespace Schemas {
* * `support_reply` - Support Reply
* * `hogdesk` - HogDesk
* * `review_hog` - ReviewHog
- * * `image_builder` - Image Builder */
+ * * `image_builder` - Image Builder
+ * * `loop` - Loop */
origin_product?: OriginProductEnum;
/**
* Target GitHub repository in `organization/repo` format (e.g. `posthog/posthog-js`).
@@ -63608,7 +64141,8 @@ export namespace Schemas {
* * `support_reply` - Support Reply
* * `hogdesk` - HogDesk
* * `review_hog` - ReviewHog
- * * `image_builder` - Image Builder */
+ * * `image_builder` - Image Builder
+ * * `loop` - Loop */
origin_product?: OriginProductEnum;
/**
* Target GitHub repository in `organization/repo` format (e.g. `posthog/posthog-js`).
@@ -72782,6 +73316,7 @@ export namespace Schemas {
* * `Metric` - Metric
* * `TableCertification` - TableCertification
* * `Billing` - Billing
+ * * `Loop` - Loop
* @minLength 1
*/
scope?: ActivityLogListScope;
@@ -72871,6 +73406,7 @@ export namespace Schemas {
Metric: 'Metric',
TableCertification: 'TableCertification',
Billing: 'Billing',
+ Loop: 'Loop',
} as const;
/**
@@ -72946,6 +73482,7 @@ export namespace Schemas {
* * `Metric` - Metric
* * `TableCertification` - TableCertification
* * `Billing` - Billing
+ * * `Loop` - Loop
*/
export type ActivityLogListScopesItem = typeof ActivityLogListScopesItem[keyof typeof ActivityLogListScopesItem];
@@ -73023,6 +73560,7 @@ export namespace Schemas {
Metric: 'Metric',
TableCertification: 'TableCertification',
Billing: 'Billing',
+ Loop: 'Loop',
} as const;
export type AdvancedActivityLogsListParams = {
@@ -78355,6 +78893,37 @@ export namespace Schemas {
offset?: number;
};
+ export type LoopsListParams = {
+ /**
+ * Number of results to return per page.
+ */
+ limit?: number;
+ /**
+ * The initial index from which to return the results.
+ */
+ offset?: number;
+ };
+
+ export type LoopsRunsRetrieveParams = {
+ /**
+ * Opaque pagination cursor from a previous response's `next_cursor`.
+ * @minLength 1
+ */
+ cursor?: string;
+ /**
+ * Max results per page (default 50, max 100).
+ * @minimum 1
+ * @maximum 100
+ */
+ limit?: number;
+ };
+
+ export type LoopsTriggerCreateBodyOne = { [key: string]: unknown };
+
+ export type LoopsTriggerCreateBodyTwo = { [key: string]: unknown };
+
+ export type LoopsTriggerCreateBodyThree = { [key: string]: unknown };
+
export type ManagedMigrationsListParams = {
/**
* Number of results to return per page.
diff --git a/services/mcp/src/generated/tasks/api.ts b/services/mcp/src/generated/tasks/api.ts
index a2014e6040a1..40eef91953a0 100644
--- a/services/mcp/src/generated/tasks/api.ts
+++ b/services/mcp/src/generated/tasks/api.ts
@@ -3,11 +3,733 @@
* MCP service uses these Zod schemas for generated tool handlers.
* To regenerate: hogli build:openapi
*
- * PostHog API - MCP 6 enabled ops
+ * PostHog API - MCP 14 enabled ops
* OpenAPI spec version: 1.0.0
*/
import * as zod from 'zod'
+/**
+ * List loops visible to the caller: personal loops they own, plus every team loop. The response also carries `max_loops_per_team` and `total_loop_count` so a client can show remaining capacity and disable creation at the cap without hardcoding the limit.
+ * @summary List loops
+ */
+export const LoopsListParams = /* @__PURE__ */ zod.object({
+ project_id: zod
+ .string()
+ .describe(
+ "Project ID of the project you're trying to access. To find the ID of the project, make a call to /api/projects/."
+ ),
+})
+
+export const LoopsListQueryParams = /* @__PURE__ */ zod.object({
+ limit: zod.number().optional().describe('Number of results to return per page.'),
+ offset: zod.number().optional().describe('The initial index from which to return the results.'),
+})
+
+/**
+ * API for managing loops — named, cloud-executed agent automations triggered by
+ * schedule, GitHub events or authenticated API calls. See `products/tasks/docs/LOOPS.md`.
+ * @summary Create a loop
+ */
+export const LoopsCreateParams = /* @__PURE__ */ zod.object({
+ project_id: zod
+ .string()
+ .describe(
+ "Project ID of the project you're trying to access. To find the ID of the project, make a call to /api/projects/."
+ ),
+})
+
+export const loopsCreateBodyNameMax = 400
+
+export const loopsCreateBodyDescriptionDefault = ``
+export const loopsCreateBodyTakeOwnershipDefault = false
+export const loopsCreateBodyVisibilityDefault = `personal`
+export const loopsCreateBodyModelDefault = ``
+export const loopsCreateBodyRepositoriesItemFullNameMax = 255
+
+export const loopsCreateBodyRepositoriesMax = 1
+
+export const loopsCreateBodyEnabledDefault = true
+export const loopsCreateBodyOverlapPolicyDefault = `skip`
+export const loopsCreateBodyBehaviorsOneCreatePrsDefault = false
+export const loopsCreateBodyBehaviorsOneWatchCiDefault = false
+export const loopsCreateBodyBehaviorsOneFixReviewCommentsDefault = false
+export const loopsCreateBodyBehaviorsOneMaxFixIterationsDefault = 3
+export const loopsCreateBodyBehaviorsOneMaxFixIterationsMin = 0
+export const loopsCreateBodyBehaviorsOneMaxFixIterationsMax = 10
+
+export const loopsCreateBodyConnectorsOnePosthogMcpScopesDefault = `read_only`
+export const loopsCreateBodyNotificationsOnePushOneEnabledDefault = false
+export const loopsCreateBodyNotificationsOneEmailOneEnabledDefault = false
+export const loopsCreateBodyNotificationsOneSlackOneEnabledDefault = false
+export const loopsCreateBodyContextTargetOneNameMax = 128
+
+export const loopsCreateBodyContextTargetOneOutputsOnePostToFeedDefault = false
+export const loopsCreateBodyContextTargetOneOutputsOneUpdateContextDefault = false
+export const loopsCreateBodyTriggersItemEnabledDefault = true
+
+export const LoopsCreateBody = /* @__PURE__ */ zod
+ .object({
+ name: zod.string().max(loopsCreateBodyNameMax).describe('Display name for the loop.'),
+ description: zod
+ .string()
+ .default(loopsCreateBodyDescriptionDefault)
+ .describe('Free-form description of what this loop does.'),
+ take_ownership: zod
+ .boolean()
+ .default(loopsCreateBodyTakeOwnershipDefault)
+ .describe(
+ 'On a team loop, claim ownership as part of this update so you can edit identity-bearing config (instructions, model, triggers, ...) that only the owner may change. Ignored on personal loops and on create.'
+ ),
+ visibility: zod
+ .enum(['personal', 'team'])
+ .describe('* `personal` - personal\n* `team` - team')
+ .default(loopsCreateBodyVisibilityDefault)
+ .describe(
+ '`personal` (owner-only) or `team` (visible and fireable by any team member).\n\n* `personal` - personal\n* `team` - team'
+ ),
+ instructions: zod.string().describe('The prompt delivered to the agent on every run.'),
+ runtime_adapter: zod
+ .enum(['claude', 'codex'])
+ .describe('* `claude` - claude\n* `codex` - codex')
+ .describe("Runtime adapter: 'claude' or 'codex'.\n\n* `claude` - claude\n* `codex` - codex"),
+ model: zod
+ .string()
+ .default(loopsCreateBodyModelDefault)
+ .describe(
+ "LLM model identifier, validated against `runtime_adapter`'s catalog. Leave blank to let PostHog pick a sensible default at run time."
+ ),
+ reasoning_effort: zod
+ .union([
+ zod
+ .enum(['low', 'medium', 'high', 'xhigh', 'max'])
+ .describe('* `low` - low\n* `medium` - medium\n* `high` - high\n* `xhigh` - xhigh\n* `max` - max'),
+ zod.null(),
+ ])
+ .optional()
+ .describe(
+ "Reasoning effort, validated against `runtime_adapter`/`model`'s supported set.\n\n* `low` - low\n* `medium` - medium\n* `high` - high\n* `xhigh` - xhigh\n* `max` - max"
+ ),
+ repositories: zod
+ .array(
+ zod.object({
+ github_integration_id: zod
+ .number()
+ .describe('GitHub integration id this repository is accessed through.'),
+ full_name: zod
+ .string()
+ .max(loopsCreateBodyRepositoriesItemFullNameMax)
+ .describe('Repository in `organization/repo` format, e.g. `posthog/posthog`.'),
+ })
+ )
+ .max(loopsCreateBodyRepositoriesMax)
+ .optional()
+ .describe(
+ 'Repositories this loop operates on, ordered. Capped at 1 until multi-repo execution ships. May be empty for report-only loops.'
+ ),
+ sandbox_environment: zod
+ .string()
+ .nullish()
+ .describe('Sandbox environment carrying encrypted env vars and the network allowlist into every run.'),
+ enabled: zod
+ .boolean()
+ .default(loopsCreateBodyEnabledDefault)
+ .describe("Whether the loop's triggers are active. Pausing disables all triggers."),
+ overlap_policy: zod
+ .enum(['skip', 'allow', 'cancel_previous'])
+ .describe('* `skip` - skip\n* `allow` - allow\n* `cancel_previous` - cancel_previous')
+ .default(loopsCreateBodyOverlapPolicyDefault)
+ .describe(
+ "What happens when a trigger fires while a run is already active: 'skip', 'allow', or 'cancel_previous'.\n\n* `skip` - skip\n* `allow` - allow\n* `cancel_previous` - cancel_previous"
+ ),
+ behaviors: zod
+ .object({
+ create_prs: zod
+ .boolean()
+ .default(loopsCreateBodyBehaviorsOneCreatePrsDefault)
+ .describe('Whether the agent may push branches and open PRs. False makes this a report-only loop.'),
+ watch_ci: zod
+ .boolean()
+ .default(loopsCreateBodyBehaviorsOneWatchCiDefault)
+ .describe('Whether to watch CI on loop-created PRs and report status.'),
+ fix_review_comments: zod
+ .boolean()
+ .default(loopsCreateBodyBehaviorsOneFixReviewCommentsDefault)
+ .describe('Whether to automatically address review comments on loop-created PRs.'),
+ max_fix_iterations: zod
+ .number()
+ .min(loopsCreateBodyBehaviorsOneMaxFixIterationsMin)
+ .max(loopsCreateBodyBehaviorsOneMaxFixIterationsMax)
+ .default(loopsCreateBodyBehaviorsOneMaxFixIterationsDefault)
+ .describe('Ceiling on automatic CI/review-comment fix iterations, capped at 10.'),
+ })
+ .optional()
+ .describe('PR / CI-follow-up behavior configuration.'),
+ connectors: zod
+ .object({
+ mcp_installation_ids: zod
+ .array(zod.string())
+ .optional()
+ .describe("MCP Store installation ids (Slack, Linear, etc.) available to this loop's runs."),
+ posthog_mcp_scopes: zod
+ .enum(['read_only', 'full'])
+ .describe('* `read_only` - read_only\n* `full` - full')
+ .default(loopsCreateBodyConnectorsOnePosthogMcpScopesDefault)
+ .describe(
+ "Scope of the PostHog MCP access injected into this loop's runs.\n\n* `read_only` - read_only\n* `full` - full"
+ ),
+ })
+ .optional()
+ .describe("MCP connector configuration for this loop's runs."),
+ notifications: zod
+ .object({
+ push: zod
+ .object({
+ enabled: zod
+ .boolean()
+ .default(loopsCreateBodyNotificationsOnePushOneEnabledDefault)
+ .describe('Whether this channel is active.'),
+ events: zod
+ .array(
+ zod
+ .enum(['run_completed', 'run_failed', 'pr_created', 'needs_attention'])
+ .describe(
+ '* `run_completed` - run_completed\n* `run_failed` - run_failed\n* `pr_created` - pr_created\n* `needs_attention` - needs_attention'
+ )
+ )
+ .optional()
+ .describe(
+ 'Event kinds this channel notifies on. One or more of: run_completed, run_failed, pr_created, needs_attention.'
+ ),
+ params: zod
+ .record(zod.string(), zod.unknown())
+ .optional()
+ .describe("Channel-specific parameters, e.g. Slack's `integration_id` and `channel`."),
+ })
+ .optional()
+ .describe('Push notification settings.'),
+ email: zod
+ .object({
+ enabled: zod
+ .boolean()
+ .default(loopsCreateBodyNotificationsOneEmailOneEnabledDefault)
+ .describe('Whether this channel is active.'),
+ events: zod
+ .array(
+ zod
+ .enum(['run_completed', 'run_failed', 'pr_created', 'needs_attention'])
+ .describe(
+ '* `run_completed` - run_completed\n* `run_failed` - run_failed\n* `pr_created` - pr_created\n* `needs_attention` - needs_attention'
+ )
+ )
+ .optional()
+ .describe(
+ 'Event kinds this channel notifies on. One or more of: run_completed, run_failed, pr_created, needs_attention.'
+ ),
+ params: zod
+ .record(zod.string(), zod.unknown())
+ .optional()
+ .describe("Channel-specific parameters, e.g. Slack's `integration_id` and `channel`."),
+ })
+ .optional()
+ .describe('Email notification settings.'),
+ slack: zod
+ .object({
+ enabled: zod
+ .boolean()
+ .default(loopsCreateBodyNotificationsOneSlackOneEnabledDefault)
+ .describe('Whether this channel is active.'),
+ events: zod
+ .array(
+ zod
+ .enum(['run_completed', 'run_failed', 'pr_created', 'needs_attention'])
+ .describe(
+ '* `run_completed` - run_completed\n* `run_failed` - run_failed\n* `pr_created` - pr_created\n* `needs_attention` - needs_attention'
+ )
+ )
+ .optional()
+ .describe(
+ 'Event kinds this channel notifies on. One or more of: run_completed, run_failed, pr_created, needs_attention.'
+ ),
+ params: zod
+ .record(zod.string(), zod.unknown())
+ .optional()
+ .describe("Channel-specific parameters, e.g. Slack's `integration_id` and `channel`."),
+ })
+ .optional()
+ .describe('Slack notification settings.'),
+ })
+ .optional()
+ .describe('Per-channel notification configuration.'),
+ context_target: zod
+ .union([
+ zod.object({
+ folder_id: zod.string().describe('Desktop folder id of the context this loop is attached to.'),
+ name: zod
+ .string()
+ .max(loopsCreateBodyContextTargetOneNameMax)
+ .describe('Context (channel) name, used to file runs into its feed.'),
+ outputs: zod
+ .object({
+ post_to_feed: zod
+ .boolean()
+ .default(loopsCreateBodyContextTargetOneOutputsOnePostToFeedDefault)
+ .describe(
+ "Whether each run is filed into the context's feed as a card (sets the run's channel)."
+ ),
+ update_context: zod
+ .boolean()
+ .default(loopsCreateBodyContextTargetOneOutputsOneUpdateContextDefault)
+ .describe(
+ "Whether each run reads and republishes the context's context.md to reflect the latest state."
+ ),
+ canvas_id: zod
+ .string()
+ .nullish()
+ .describe(
+ 'Id of a canvas in this context the loop keeps up to date each run, or null to maintain none.'
+ ),
+ })
+ .optional()
+ .describe('What the loop maintains in this context each run.'),
+ }),
+ zod.null(),
+ ])
+ .optional()
+ .describe(
+ 'Context (channel) this loop is attached to, or null to detach. Drives feed placement and the context.md / canvas it keeps up to date.'
+ ),
+ triggers: zod
+ .array(
+ zod.object({
+ id: zod
+ .string()
+ .optional()
+ .describe('Existing trigger id to update in place. Omit to create a new trigger.'),
+ type: zod
+ .enum(['schedule', 'github', 'api'])
+ .describe('* `schedule` - schedule\n* `github` - github\n* `api` - api')
+ .describe(
+ 'Trigger type: `schedule` (cron or one-time), `github` (repo webhook events), or `api` (POST to `trigger/`).\n\n* `schedule` - schedule\n* `github` - github\n* `api` - api'
+ ),
+ enabled: zod
+ .boolean()
+ .default(loopsCreateBodyTriggersItemEnabledDefault)
+ .describe('Whether this trigger is active. Disabling pauses only this trigger.'),
+ config: zod
+ .unknown()
+ .optional()
+ .describe(
+ 'Trigger configuration, shape validated per `type`: schedule takes `{cron_expression, timezone}` or `{run_at}` for a one-time run; github takes `{github_integration_id, repository, events, filters}`; api takes no config.'
+ ),
+ })
+ )
+ .optional()
+ .describe(
+ 'Full desired trigger list, id-stable: entries with a matching `id` are updated in place, entries without one are created, and existing triggers absent from this list are deleted. Omit the field entirely to leave triggers untouched. At most 25 triggers per loop.'
+ ),
+ })
+ .describe(
+ 'Request body for creating or updating a loop. Field required/default semantics match\nthe `Loop` model; partial updates only touch keys present in the payload.'
+ )
+
+/**
+ * API for managing loops — named, cloud-executed agent automations triggered by
+ * schedule, GitHub events or authenticated API calls. See `products/tasks/docs/LOOPS.md`.
+ * @summary Get a loop
+ */
+export const LoopsRetrieveParams = /* @__PURE__ */ zod.object({
+ id: zod.string(),
+ project_id: zod
+ .string()
+ .describe(
+ "Project ID of the project you're trying to access. To find the ID of the project, make a call to /api/projects/."
+ ),
+})
+
+/**
+ * Partial update. Identity-bearing fields (instructions, repositories, connectors, behaviors, model config, triggers) are owner-only on team loops; name, description, notifications and enable/pause are editable by any team member.
+ * @summary Update a loop
+ */
+export const LoopsPartialUpdateParams = /* @__PURE__ */ zod.object({
+ id: zod.string(),
+ project_id: zod
+ .string()
+ .describe(
+ "Project ID of the project you're trying to access. To find the ID of the project, make a call to /api/projects/."
+ ),
+})
+
+export const loopsPartialUpdateBodyNameMax = 400
+
+export const loopsPartialUpdateBodyRepositoriesItemFullNameMax = 255
+
+export const loopsPartialUpdateBodyRepositoriesMax = 1
+
+export const loopsPartialUpdateBodyBehaviorsOneCreatePrsDefault = false
+export const loopsPartialUpdateBodyBehaviorsOneWatchCiDefault = false
+export const loopsPartialUpdateBodyBehaviorsOneFixReviewCommentsDefault = false
+export const loopsPartialUpdateBodyBehaviorsOneMaxFixIterationsDefault = 3
+export const loopsPartialUpdateBodyBehaviorsOneMaxFixIterationsMin = 0
+export const loopsPartialUpdateBodyBehaviorsOneMaxFixIterationsMax = 10
+
+export const loopsPartialUpdateBodyConnectorsOnePosthogMcpScopesDefault = `read_only`
+export const loopsPartialUpdateBodyNotificationsOnePushOneEnabledDefault = false
+export const loopsPartialUpdateBodyNotificationsOneEmailOneEnabledDefault = false
+export const loopsPartialUpdateBodyNotificationsOneSlackOneEnabledDefault = false
+export const loopsPartialUpdateBodyContextTargetOneNameMax = 128
+
+export const loopsPartialUpdateBodyContextTargetOneOutputsOnePostToFeedDefault = false
+export const loopsPartialUpdateBodyContextTargetOneOutputsOneUpdateContextDefault = false
+export const loopsPartialUpdateBodyTriggersItemEnabledDefault = true
+
+export const LoopsPartialUpdateBody = /* @__PURE__ */ zod
+ .object({
+ name: zod.string().max(loopsPartialUpdateBodyNameMax).optional().describe('Display name for the loop.'),
+ description: zod.string().optional().describe('Free-form description of what this loop does.'),
+ take_ownership: zod
+ .boolean()
+ .optional()
+ .describe(
+ 'On a team loop, claim ownership as part of this update so you can edit identity-bearing config (instructions, model, triggers, ...) that only the owner may change. Ignored on personal loops and on create.'
+ ),
+ visibility: zod
+ .enum(['personal', 'team'])
+ .describe('* `personal` - personal\n* `team` - team')
+ .optional()
+ .describe(
+ '`personal` (owner-only) or `team` (visible and fireable by any team member).\n\n* `personal` - personal\n* `team` - team'
+ ),
+ instructions: zod.string().optional().describe('The prompt delivered to the agent on every run.'),
+ runtime_adapter: zod
+ .enum(['claude', 'codex'])
+ .describe('* `claude` - claude\n* `codex` - codex')
+ .optional()
+ .describe("Runtime adapter: 'claude' or 'codex'.\n\n* `claude` - claude\n* `codex` - codex"),
+ model: zod
+ .string()
+ .optional()
+ .describe(
+ "LLM model identifier, validated against `runtime_adapter`'s catalog. Leave blank to let PostHog pick a sensible default at run time."
+ ),
+ reasoning_effort: zod
+ .union([
+ zod
+ .enum(['low', 'medium', 'high', 'xhigh', 'max'])
+ .describe('* `low` - low\n* `medium` - medium\n* `high` - high\n* `xhigh` - xhigh\n* `max` - max'),
+ zod.null(),
+ ])
+ .optional()
+ .describe(
+ "Reasoning effort, validated against `runtime_adapter`/`model`'s supported set.\n\n* `low` - low\n* `medium` - medium\n* `high` - high\n* `xhigh` - xhigh\n* `max` - max"
+ ),
+ repositories: zod
+ .array(
+ zod.object({
+ github_integration_id: zod
+ .number()
+ .describe('GitHub integration id this repository is accessed through.'),
+ full_name: zod
+ .string()
+ .max(loopsPartialUpdateBodyRepositoriesItemFullNameMax)
+ .describe('Repository in `organization/repo` format, e.g. `posthog/posthog`.'),
+ })
+ )
+ .max(loopsPartialUpdateBodyRepositoriesMax)
+ .optional()
+ .describe(
+ 'Repositories this loop operates on, ordered. Capped at 1 until multi-repo execution ships. May be empty for report-only loops.'
+ ),
+ sandbox_environment: zod
+ .string()
+ .nullish()
+ .describe('Sandbox environment carrying encrypted env vars and the network allowlist into every run.'),
+ enabled: zod
+ .boolean()
+ .optional()
+ .describe("Whether the loop's triggers are active. Pausing disables all triggers."),
+ overlap_policy: zod
+ .enum(['skip', 'allow', 'cancel_previous'])
+ .describe('* `skip` - skip\n* `allow` - allow\n* `cancel_previous` - cancel_previous')
+ .optional()
+ .describe(
+ "What happens when a trigger fires while a run is already active: 'skip', 'allow', or 'cancel_previous'.\n\n* `skip` - skip\n* `allow` - allow\n* `cancel_previous` - cancel_previous"
+ ),
+ behaviors: zod
+ .object({
+ create_prs: zod
+ .boolean()
+ .default(loopsPartialUpdateBodyBehaviorsOneCreatePrsDefault)
+ .describe('Whether the agent may push branches and open PRs. False makes this a report-only loop.'),
+ watch_ci: zod
+ .boolean()
+ .default(loopsPartialUpdateBodyBehaviorsOneWatchCiDefault)
+ .describe('Whether to watch CI on loop-created PRs and report status.'),
+ fix_review_comments: zod
+ .boolean()
+ .default(loopsPartialUpdateBodyBehaviorsOneFixReviewCommentsDefault)
+ .describe('Whether to automatically address review comments on loop-created PRs.'),
+ max_fix_iterations: zod
+ .number()
+ .min(loopsPartialUpdateBodyBehaviorsOneMaxFixIterationsMin)
+ .max(loopsPartialUpdateBodyBehaviorsOneMaxFixIterationsMax)
+ .default(loopsPartialUpdateBodyBehaviorsOneMaxFixIterationsDefault)
+ .describe('Ceiling on automatic CI/review-comment fix iterations, capped at 10.'),
+ })
+ .optional()
+ .describe('PR / CI-follow-up behavior configuration.'),
+ connectors: zod
+ .object({
+ mcp_installation_ids: zod
+ .array(zod.string())
+ .optional()
+ .describe("MCP Store installation ids (Slack, Linear, etc.) available to this loop's runs."),
+ posthog_mcp_scopes: zod
+ .enum(['read_only', 'full'])
+ .describe('* `read_only` - read_only\n* `full` - full')
+ .default(loopsPartialUpdateBodyConnectorsOnePosthogMcpScopesDefault)
+ .describe(
+ "Scope of the PostHog MCP access injected into this loop's runs.\n\n* `read_only` - read_only\n* `full` - full"
+ ),
+ })
+ .optional()
+ .describe("MCP connector configuration for this loop's runs."),
+ notifications: zod
+ .object({
+ push: zod
+ .object({
+ enabled: zod
+ .boolean()
+ .default(loopsPartialUpdateBodyNotificationsOnePushOneEnabledDefault)
+ .describe('Whether this channel is active.'),
+ events: zod
+ .array(
+ zod
+ .enum(['run_completed', 'run_failed', 'pr_created', 'needs_attention'])
+ .describe(
+ '* `run_completed` - run_completed\n* `run_failed` - run_failed\n* `pr_created` - pr_created\n* `needs_attention` - needs_attention'
+ )
+ )
+ .optional()
+ .describe(
+ 'Event kinds this channel notifies on. One or more of: run_completed, run_failed, pr_created, needs_attention.'
+ ),
+ params: zod
+ .record(zod.string(), zod.unknown())
+ .optional()
+ .describe("Channel-specific parameters, e.g. Slack's `integration_id` and `channel`."),
+ })
+ .optional()
+ .describe('Push notification settings.'),
+ email: zod
+ .object({
+ enabled: zod
+ .boolean()
+ .default(loopsPartialUpdateBodyNotificationsOneEmailOneEnabledDefault)
+ .describe('Whether this channel is active.'),
+ events: zod
+ .array(
+ zod
+ .enum(['run_completed', 'run_failed', 'pr_created', 'needs_attention'])
+ .describe(
+ '* `run_completed` - run_completed\n* `run_failed` - run_failed\n* `pr_created` - pr_created\n* `needs_attention` - needs_attention'
+ )
+ )
+ .optional()
+ .describe(
+ 'Event kinds this channel notifies on. One or more of: run_completed, run_failed, pr_created, needs_attention.'
+ ),
+ params: zod
+ .record(zod.string(), zod.unknown())
+ .optional()
+ .describe("Channel-specific parameters, e.g. Slack's `integration_id` and `channel`."),
+ })
+ .optional()
+ .describe('Email notification settings.'),
+ slack: zod
+ .object({
+ enabled: zod
+ .boolean()
+ .default(loopsPartialUpdateBodyNotificationsOneSlackOneEnabledDefault)
+ .describe('Whether this channel is active.'),
+ events: zod
+ .array(
+ zod
+ .enum(['run_completed', 'run_failed', 'pr_created', 'needs_attention'])
+ .describe(
+ '* `run_completed` - run_completed\n* `run_failed` - run_failed\n* `pr_created` - pr_created\n* `needs_attention` - needs_attention'
+ )
+ )
+ .optional()
+ .describe(
+ 'Event kinds this channel notifies on. One or more of: run_completed, run_failed, pr_created, needs_attention.'
+ ),
+ params: zod
+ .record(zod.string(), zod.unknown())
+ .optional()
+ .describe("Channel-specific parameters, e.g. Slack's `integration_id` and `channel`."),
+ })
+ .optional()
+ .describe('Slack notification settings.'),
+ })
+ .optional()
+ .describe('Per-channel notification configuration.'),
+ context_target: zod
+ .union([
+ zod.object({
+ folder_id: zod.string().describe('Desktop folder id of the context this loop is attached to.'),
+ name: zod
+ .string()
+ .max(loopsPartialUpdateBodyContextTargetOneNameMax)
+ .describe('Context (channel) name, used to file runs into its feed.'),
+ outputs: zod
+ .object({
+ post_to_feed: zod
+ .boolean()
+ .default(loopsPartialUpdateBodyContextTargetOneOutputsOnePostToFeedDefault)
+ .describe(
+ "Whether each run is filed into the context's feed as a card (sets the run's channel)."
+ ),
+ update_context: zod
+ .boolean()
+ .default(loopsPartialUpdateBodyContextTargetOneOutputsOneUpdateContextDefault)
+ .describe(
+ "Whether each run reads and republishes the context's context.md to reflect the latest state."
+ ),
+ canvas_id: zod
+ .string()
+ .nullish()
+ .describe(
+ 'Id of a canvas in this context the loop keeps up to date each run, or null to maintain none.'
+ ),
+ })
+ .optional()
+ .describe('What the loop maintains in this context each run.'),
+ }),
+ zod.null(),
+ ])
+ .optional()
+ .describe(
+ 'Context (channel) this loop is attached to, or null to detach. Drives feed placement and the context.md / canvas it keeps up to date.'
+ ),
+ triggers: zod
+ .array(
+ zod.object({
+ id: zod
+ .string()
+ .optional()
+ .describe('Existing trigger id to update in place. Omit to create a new trigger.'),
+ type: zod
+ .enum(['schedule', 'github', 'api'])
+ .describe('* `schedule` - schedule\n* `github` - github\n* `api` - api')
+ .describe(
+ 'Trigger type: `schedule` (cron or one-time), `github` (repo webhook events), or `api` (POST to `trigger/`).\n\n* `schedule` - schedule\n* `github` - github\n* `api` - api'
+ ),
+ enabled: zod
+ .boolean()
+ .default(loopsPartialUpdateBodyTriggersItemEnabledDefault)
+ .describe('Whether this trigger is active. Disabling pauses only this trigger.'),
+ config: zod
+ .unknown()
+ .optional()
+ .describe(
+ 'Trigger configuration, shape validated per `type`: schedule takes `{cron_expression, timezone}` or `{run_at}` for a one-time run; github takes `{github_integration_id, repository, events, filters}`; api takes no config.'
+ ),
+ })
+ )
+ .optional()
+ .describe(
+ 'Full desired trigger list, id-stable: entries with a matching `id` are updated in place, entries without one are created, and existing triggers absent from this list are deleted. Omit the field entirely to leave triggers untouched. At most 25 triggers per loop.'
+ ),
+ })
+ .describe(
+ 'Request body for creating or updating a loop. Field required/default semantics match\nthe `Loop` model; partial updates only touch keys present in the payload.'
+ )
+
+/**
+ * Soft delete. Pauses every trigger's schedule. Owner or a project admin only.
+ * @summary Delete a loop
+ */
+export const LoopsDestroyParams = /* @__PURE__ */ zod.object({
+ id: zod.string(),
+ project_id: zod
+ .string()
+ .describe(
+ "Project ID of the project you're trying to access. To find the ID of the project, make a call to /api/projects/."
+ ),
+})
+
+/**
+ * Dry run: renders the assembled instructions and trigger context for a supplied sample payload (or a synthetic schedule fire when omitted), without creating a task, run, or any other side effect.
+ * @summary Preview a loop fire
+ */
+export const LoopsPreviewCreateParams = /* @__PURE__ */ zod.object({
+ id: zod.string(),
+ project_id: zod
+ .string()
+ .describe(
+ "Project ID of the project you're trying to access. To find the ID of the project, make a call to /api/projects/."
+ ),
+})
+
+export const loopsPreviewCreateBodyTriggerTypeDefault = `schedule`
+
+export const LoopsPreviewCreateBody = /* @__PURE__ */ zod.object({
+ trigger_type: zod
+ .enum(['schedule', 'github', 'api'])
+ .describe('* `schedule` - schedule\n* `github` - github\n* `api` - api')
+ .default(loopsPreviewCreateBodyTriggerTypeDefault)
+ .describe(
+ 'Trigger type to simulate. Defaults to a synthetic schedule fire.\n\n* `schedule` - schedule\n* `github` - github\n* `api` - api'
+ ),
+ payload: zod
+ .unknown()
+ .optional()
+ .describe('Sample trigger payload, e.g. a GitHub webhook body or an API trigger body, to render into context.'),
+})
+
+/**
+ * Manual fire from the UI. Owner-only for personal loops; any team member for team loops.
+ * @summary Run a loop manually
+ */
+export const LoopsRunCreateParams = /* @__PURE__ */ zod.object({
+ id: zod.string(),
+ project_id: zod
+ .string()
+ .describe(
+ "Project ID of the project you're trying to access. To find the ID of the project, make a call to /api/projects/."
+ ),
+})
+
+/**
+ * Run history for a loop, newest first, cursor-paginated.
+ * @summary List loop runs
+ */
+export const LoopsRunsRetrieveParams = /* @__PURE__ */ zod.object({
+ id: zod.string(),
+ project_id: zod
+ .string()
+ .describe(
+ "Project ID of the project you're trying to access. To find the ID of the project, make a call to /api/projects/."
+ ),
+})
+
+export const loopsRunsRetrieveQueryLimitDefault = 50
+export const loopsRunsRetrieveQueryLimitMax = 100
+
+export const LoopsRunsRetrieveQueryParams = /* @__PURE__ */ zod.object({
+ cursor: zod
+ .string()
+ .min(1)
+ .optional()
+ .describe("Opaque pagination cursor from a previous response's `next_cursor`."),
+ limit: zod
+ .number()
+ .min(1)
+ .max(loopsRunsRetrieveQueryLimitMax)
+ .default(loopsRunsRetrieveQueryLimitDefault)
+ .describe('Max results per page (default 50, max 100).'),
+})
+
/**
* Get a list of tasks for the current project, with optional filtering by origin product, stage, organization, repository, and created_by.
* @summary List tasks
@@ -131,13 +853,14 @@ export const TasksCreateBody = /* @__PURE__ */ zod
'hogdesk',
'review_hog',
'image_builder',
+ 'loop',
])
.describe(
- '* `onboarding` - Onboarding\n* `error_tracking` - Error Tracking\n* `eval_clusters` - Eval Clusters\n* `user_created` - User Created\n* `automation` - Automation\n* `slack` - Slack\n* `support_queue` - Support Queue\n* `session_summaries` - Session Summaries\n* `posthog_ai` - PostHog AI\n* `experiments` - Experiments\n* `signal_report` - Signal Report\n* `signals_scout` - Signals Scout\n* `support_reply` - Support Reply\n* `hogdesk` - HogDesk\n* `review_hog` - ReviewHog\n* `image_builder` - Image Builder'
+ '* `onboarding` - Onboarding\n* `error_tracking` - Error Tracking\n* `eval_clusters` - Eval Clusters\n* `user_created` - User Created\n* `automation` - Automation\n* `slack` - Slack\n* `support_queue` - Support Queue\n* `session_summaries` - Session Summaries\n* `posthog_ai` - PostHog AI\n* `experiments` - Experiments\n* `signal_report` - Signal Report\n* `signals_scout` - Signals Scout\n* `support_reply` - Support Reply\n* `hogdesk` - HogDesk\n* `review_hog` - ReviewHog\n* `image_builder` - Image Builder\n* `loop` - Loop'
)
.optional()
.describe(
- 'PostHog product or surface that created this task (e.g. error_tracking, slack, user_created).\n\n* `onboarding` - Onboarding\n* `error_tracking` - Error Tracking\n* `eval_clusters` - Eval Clusters\n* `user_created` - User Created\n* `automation` - Automation\n* `slack` - Slack\n* `support_queue` - Support Queue\n* `session_summaries` - Session Summaries\n* `posthog_ai` - PostHog AI\n* `experiments` - Experiments\n* `signal_report` - Signal Report\n* `signals_scout` - Signals Scout\n* `support_reply` - Support Reply\n* `hogdesk` - HogDesk\n* `review_hog` - ReviewHog\n* `image_builder` - Image Builder'
+ 'PostHog product or surface that created this task (e.g. error_tracking, slack, user_created).\n\n* `onboarding` - Onboarding\n* `error_tracking` - Error Tracking\n* `eval_clusters` - Eval Clusters\n* `user_created` - User Created\n* `automation` - Automation\n* `slack` - Slack\n* `support_queue` - Support Queue\n* `session_summaries` - Session Summaries\n* `posthog_ai` - PostHog AI\n* `experiments` - Experiments\n* `signal_report` - Signal Report\n* `signals_scout` - Signals Scout\n* `support_reply` - Support Reply\n* `hogdesk` - HogDesk\n* `review_hog` - ReviewHog\n* `image_builder` - Image Builder\n* `loop` - Loop'
),
repository: zod
.string()
diff --git a/services/mcp/src/lib/oauth-scopes.generated.ts b/services/mcp/src/lib/oauth-scopes.generated.ts
index fbfb2043150c..909a42c1ab38 100644
--- a/services/mcp/src/lib/oauth-scopes.generated.ts
+++ b/services/mcp/src/lib/oauth-scopes.generated.ts
@@ -125,6 +125,8 @@ export const OAUTH_SCOPES_SUPPORTED = [
'llm_skill:write',
'logs:read',
'logs:write',
+ 'loop:read',
+ 'loop:write',
'marketing_analytics:read',
'marketing_analytics:write',
'mcp_analytics:read',
diff --git a/services/mcp/src/resources/ui-apps.generated.ts b/services/mcp/src/resources/ui-apps.generated.ts
index 869db2aad271..1f4dae4c8bd0 100644
--- a/services/mcp/src/resources/ui-apps.generated.ts
+++ b/services/mcp/src/resources/ui-apps.generated.ts
@@ -18,6 +18,7 @@ export const FEATURE_FLAG_TESTING_RESOURCE_URI = 'ui://posthog/feature-flag-test
export const INSIGHT_ACTORS_RESOURCE_URI = 'ui://posthog/insight-actors.html'
export const INVITE_EMAIL_PREVIEW_RESOURCE_URI = 'ui://posthog/invite-email-preview.html'
export const LLM_COSTS_RESOURCE_URI = 'ui://posthog/llm-costs.html'
+export const LOOPS_REVIEW_RESOURCE_URI = 'ui://posthog/loops-review.html'
export const QUERY_RESULTS_RESOURCE_URI = 'ui://posthog/query-results.html'
export const RENDER_UI_RESOURCE_URI = 'ui://posthog/render-ui.html'
export const SESSION_RECORDING_RESOURCE_URI = 'ui://posthog/session-recording.html'
@@ -51,6 +52,7 @@ export type UiAppKey =
| 'insight-actors'
| 'invite-email-preview'
| 'llm-costs'
+ | 'loops-review'
| 'query-results'
| 'render-ui'
| 'session-recording'
@@ -84,6 +86,7 @@ export const URI_MAP: Record = {
'insight-actors': INSIGHT_ACTORS_RESOURCE_URI,
'invite-email-preview': INVITE_EMAIL_PREVIEW_RESOURCE_URI,
'llm-costs': LLM_COSTS_RESOURCE_URI,
+ 'loops-review': LOOPS_REVIEW_RESOURCE_URI,
'query-results': QUERY_RESULTS_RESOURCE_URI,
'render-ui': RENDER_UI_RESOURCE_URI,
'session-recording': SESSION_RECORDING_RESOURCE_URI,
@@ -248,6 +251,12 @@ export const UI_APPS: Array<{
description: 'Llm Costs detail view',
appDir: 'generated/llm-costs',
},
+ {
+ name: 'PostHog Loop Review',
+ uri: LOOPS_REVIEW_RESOURCE_URI,
+ description: 'Review card for a loop before creation, with a Create loop action.',
+ appDir: 'loops-review',
+ },
{
name: 'Query Results',
uri: QUERY_RESULTS_RESOURCE_URI,
diff --git a/services/mcp/src/schema/tool-inputs.ts b/services/mcp/src/schema/tool-inputs.ts
index e46cfced0172..c3e526664285 100644
--- a/services/mcp/src/schema/tool-inputs.ts
+++ b/services/mcp/src/schema/tool-inputs.ts
@@ -179,121 +179,125 @@ export const PromptListInputSchema = z.object({
),
})
-export const FeedbackSubmitSchema = z.object({
- summary: z
- .string()
- .min(1)
- .describe(
- 'A one-sentence headline capturing the feedback (e.g. "session replay scrubber jumps backwards when you click the timeline", "query-trends descriptions made it hard to choose between trends and funnels", or "the new SQL editor autocomplete is excellent").'
- ),
- feedback_type: z
- .enum(['product', 'mcp', 'docs', 'scout', 'other'])
- .describe(
- 'What this feedback is about. "product" = any PostHog product or feature (insights, session replay, feature flags, the data warehouse, web analytics, error tracking, etc.). "mcp" = this MCP server itself — a tool, its input schema, response format, an error, or these instructions. "docs" = PostHog documentation. "scout" = a canonical PostHog scout skill\'s content — reserved for scheduled scout runs reporting an improvement opportunity in their own PostHog-authored skill (set `scout_skill_name`, `scout_skill_version`, and `scout_category`). "other" = anything that doesn\'t fit the above.'
- ),
- sentiment: z
- .enum(['positive', 'neutral', 'negative', 'mixed'])
- .describe(
- 'The overall tone. Use "negative" for something broken or blocking, "mixed" for mostly-fine-but-with-a-concrete-problem, "neutral" for a suggestion or feature request with no strong sentiment, and "positive" for praise or something that worked well. All sentiments are welcome — positive feedback is encouraged, not just problems.'
- ),
- product_area: z
- .string()
- .optional()
- .describe(
- 'The PostHog product or area this is about, in free text (e.g. "session replay", "insights", "data warehouse", "feature flags", "docs"). Most useful for product feedback; for MCP feedback the tool name belongs in `details`/`friction_points` instead.'
- ),
- category: z
- .enum([
- 'tool_correctness',
- 'tool_description',
- 'tool_input_schema',
- 'tool_output_format',
- 'missing_tool',
- 'instructions_clarity',
- 'performance',
- 'error_message',
- 'other',
- ])
- .optional()
- .describe(
- 'For MCP feedback (`feedback_type: "mcp"`) only: the single category that best describes the dominant theme. Pick "missing_tool" if a capability was absent, "tool_description" if the tool docs were unclear, "tool_input_schema" if input args were confusing, "tool_output_format" if the response was hard to consume, "instructions_clarity" if these MCP instructions were unclear, "tool_correctness" if a tool returned wrong data, "error_message" if an error was unhelpful, "performance" if latency was the issue. Omit for product, docs, or other feedback.'
- ),
- scout_skill_name: z
- .string()
- .optional()
- .describe(
- 'For scout feedback (`feedback_type: "scout"`) only: the canonical scout skill the feedback is about (e.g. "signals-scout-web-analytics"), exactly as named in the run identity. Required for scout feedback — without it the feedback cannot be aggregated per skill.'
- ),
- scout_skill_version: z
- .number()
- .int()
- .optional()
- .describe(
- 'For scout feedback (`feedback_type: "scout"`) only: the skill version the run executed (from the run identity). Feedback is only actionable against the version that produced it — the skill may have moved since.'
- ),
- scout_category: z
- .enum([
- 'false_positive',
- 'missed_detection',
- 'discriminator_gap',
- 'wasted_investigation',
- 'instruction_ambiguity',
- 'other',
- ])
- .optional()
- .describe(
- 'For scout feedback (`feedback_type: "scout"`) only: the single category that best describes the skill gap. "false_positive" = the skill\'s detection rules surfaced something that wasn\'t real; "missed_detection" = a real issue the skill\'s instructions steered you past; "discriminator_gap" = the skill\'s signal-vs-baseline discriminator doesn\'t hold for a class of projects; "wasted_investigation" = an investigation pattern the skill mandates burned budget without payoff; "instruction_ambiguity" = an instruction that is ambiguous in practice. Omit for non-scout feedback.'
- ),
- task_completed: z
- .boolean()
- .optional()
- .describe(
- 'Were you able to complete the user\'s task? Be honest — "false" is just as useful as "true". Most relevant when `feedback_type` is "mcp".'
- ),
- tools_used: z
- .array(z.string())
- .optional()
- .describe(
- 'The MCP tool names you called while working on the user\'s task (e.g. ["read-data-schema", "query-trends"]). Helps us correlate feedback to specific tools.'
- ),
- friction_points: z
- .string()
- .optional()
- .describe(
- 'Clear, concise bullet points describing the friction — what was confusing, broken, slow, or missing. Quote the exact product surface, tool name, parameter, or error text where you can. Omit for purely positive feedback.'
- ),
- suggested_improvement: z
- .string()
- .optional()
- .describe(
- 'The single most impactful, concrete change that would address this feedback, if you can name one (e.g. "add a `filters` example to query-funnel\'s description", or "let the replay scrubber snap to the nearest event"). Optional — praise or an observation doesn\'t need one.'
- ),
- user_request: z
- .string()
- .optional()
- .describe(
- 'A short, anonymised paraphrase of what the user originally asked you to do. Do not include PII, customer names, or sensitive query content.'
- ),
- details: z
- .string()
- .optional()
- .describe("Any additional context that doesn't fit the other fields. Keep it to clear, concise bullet points."),
-}).superRefine((data, ctx) => {
- // Scout feedback without its join keys can't be aggregated per skill/version downstream,
- // so reject it at validation time instead of recording an unattributable event.
- if (data.feedback_type !== 'scout') {
- return
- }
- for (const field of ['scout_skill_name', 'scout_skill_version', 'scout_category'] as const) {
- if (data[field] === undefined) {
- ctx.addIssue({
- code: 'custom',
- path: [field],
- message: `${field} is required when feedback_type is "scout".`,
- })
+export const FeedbackSubmitSchema = z
+ .object({
+ summary: z
+ .string()
+ .min(1)
+ .describe(
+ 'A one-sentence headline capturing the feedback (e.g. "session replay scrubber jumps backwards when you click the timeline", "query-trends descriptions made it hard to choose between trends and funnels", or "the new SQL editor autocomplete is excellent").'
+ ),
+ feedback_type: z
+ .enum(['product', 'mcp', 'docs', 'scout', 'other'])
+ .describe(
+ 'What this feedback is about. "product" = any PostHog product or feature (insights, session replay, feature flags, the data warehouse, web analytics, error tracking, etc.). "mcp" = this MCP server itself — a tool, its input schema, response format, an error, or these instructions. "docs" = PostHog documentation. "scout" = a canonical PostHog scout skill\'s content — reserved for scheduled scout runs reporting an improvement opportunity in their own PostHog-authored skill (set `scout_skill_name`, `scout_skill_version`, and `scout_category`). "other" = anything that doesn\'t fit the above.'
+ ),
+ sentiment: z
+ .enum(['positive', 'neutral', 'negative', 'mixed'])
+ .describe(
+ 'The overall tone. Use "negative" for something broken or blocking, "mixed" for mostly-fine-but-with-a-concrete-problem, "neutral" for a suggestion or feature request with no strong sentiment, and "positive" for praise or something that worked well. All sentiments are welcome — positive feedback is encouraged, not just problems.'
+ ),
+ product_area: z
+ .string()
+ .optional()
+ .describe(
+ 'The PostHog product or area this is about, in free text (e.g. "session replay", "insights", "data warehouse", "feature flags", "docs"). Most useful for product feedback; for MCP feedback the tool name belongs in `details`/`friction_points` instead.'
+ ),
+ category: z
+ .enum([
+ 'tool_correctness',
+ 'tool_description',
+ 'tool_input_schema',
+ 'tool_output_format',
+ 'missing_tool',
+ 'instructions_clarity',
+ 'performance',
+ 'error_message',
+ 'other',
+ ])
+ .optional()
+ .describe(
+ 'For MCP feedback (`feedback_type: "mcp"`) only: the single category that best describes the dominant theme. Pick "missing_tool" if a capability was absent, "tool_description" if the tool docs were unclear, "tool_input_schema" if input args were confusing, "tool_output_format" if the response was hard to consume, "instructions_clarity" if these MCP instructions were unclear, "tool_correctness" if a tool returned wrong data, "error_message" if an error was unhelpful, "performance" if latency was the issue. Omit for product, docs, or other feedback.'
+ ),
+ scout_skill_name: z
+ .string()
+ .optional()
+ .describe(
+ 'For scout feedback (`feedback_type: "scout"`) only: the canonical scout skill the feedback is about (e.g. "signals-scout-web-analytics"), exactly as named in the run identity. Required for scout feedback — without it the feedback cannot be aggregated per skill.'
+ ),
+ scout_skill_version: z
+ .number()
+ .int()
+ .optional()
+ .describe(
+ 'For scout feedback (`feedback_type: "scout"`) only: the skill version the run executed (from the run identity). Feedback is only actionable against the version that produced it — the skill may have moved since.'
+ ),
+ scout_category: z
+ .enum([
+ 'false_positive',
+ 'missed_detection',
+ 'discriminator_gap',
+ 'wasted_investigation',
+ 'instruction_ambiguity',
+ 'other',
+ ])
+ .optional()
+ .describe(
+ 'For scout feedback (`feedback_type: "scout"`) only: the single category that best describes the skill gap. "false_positive" = the skill\'s detection rules surfaced something that wasn\'t real; "missed_detection" = a real issue the skill\'s instructions steered you past; "discriminator_gap" = the skill\'s signal-vs-baseline discriminator doesn\'t hold for a class of projects; "wasted_investigation" = an investigation pattern the skill mandates burned budget without payoff; "instruction_ambiguity" = an instruction that is ambiguous in practice. Omit for non-scout feedback.'
+ ),
+ task_completed: z
+ .boolean()
+ .optional()
+ .describe(
+ 'Were you able to complete the user\'s task? Be honest — "false" is just as useful as "true". Most relevant when `feedback_type` is "mcp".'
+ ),
+ tools_used: z
+ .array(z.string())
+ .optional()
+ .describe(
+ 'The MCP tool names you called while working on the user\'s task (e.g. ["read-data-schema", "query-trends"]). Helps us correlate feedback to specific tools.'
+ ),
+ friction_points: z
+ .string()
+ .optional()
+ .describe(
+ 'Clear, concise bullet points describing the friction — what was confusing, broken, slow, or missing. Quote the exact product surface, tool name, parameter, or error text where you can. Omit for purely positive feedback.'
+ ),
+ suggested_improvement: z
+ .string()
+ .optional()
+ .describe(
+ 'The single most impactful, concrete change that would address this feedback, if you can name one (e.g. "add a `filters` example to query-funnel\'s description", or "let the replay scrubber snap to the nearest event"). Optional — praise or an observation doesn\'t need one.'
+ ),
+ user_request: z
+ .string()
+ .optional()
+ .describe(
+ 'A short, anonymised paraphrase of what the user originally asked you to do. Do not include PII, customer names, or sensitive query content.'
+ ),
+ details: z
+ .string()
+ .optional()
+ .describe(
+ "Any additional context that doesn't fit the other fields. Keep it to clear, concise bullet points."
+ ),
+ })
+ .superRefine((data, ctx) => {
+ // Scout feedback without its join keys can't be aggregated per skill/version downstream,
+ // so reject it at validation time instead of recording an unattributable event.
+ if (data.feedback_type !== 'scout') {
+ return
}
- }
-})
+ for (const field of ['scout_skill_name', 'scout_skill_version', 'scout_category'] as const) {
+ if (data[field] === undefined) {
+ ctx.addIssue({
+ code: 'custom',
+ path: [field],
+ message: `${field} is required when feedback_type is "scout".`,
+ })
+ }
+ }
+ })
const SavedMetricAttachItemSchema = z.object({
id: z
diff --git a/services/mcp/src/tools/generated/tasks.ts b/services/mcp/src/tools/generated/tasks.ts
index 84c0fd5c2f77..f9b56ce5ca60 100644
--- a/services/mcp/src/tools/generated/tasks.ts
+++ b/services/mcp/src/tools/generated/tasks.ts
@@ -3,6 +3,17 @@ import { z } from 'zod'
import type { Schemas } from '@/api/generated'
import {
+ LoopsCreateBody,
+ LoopsDestroyParams,
+ LoopsListQueryParams,
+ LoopsPartialUpdateBody,
+ LoopsPartialUpdateParams,
+ LoopsPreviewCreateBody,
+ LoopsPreviewCreateParams,
+ LoopsRetrieveParams,
+ LoopsRunCreateParams,
+ LoopsRunsRetrieveParams,
+ LoopsRunsRetrieveQueryParams,
TasksCreateBody,
TasksListQueryParams,
TasksRetrieveParams,
@@ -12,9 +23,310 @@ import {
TasksRunsSessionLogsRetrieveParams,
TasksRunsSessionLogsRetrieveQueryParams,
} from '@/generated/tasks/api'
+import { getConfirmedActionRuntime } from '@/tools/confirmed-action-registry'
+import {
+ executeConfirmedAction,
+ prepareConfirmedAction,
+ type PrepareConfirmedActionResult,
+} from '@/tools/confirmed-action-runtime'
import { withPostHogUrl, pickResponseFields, omitResponseFields, type WithPostHogUrl } from '@/tools/tool-utils'
import type { Context, ToolBase, ZodObjectAny } from '@/tools/types'
+const LoopsCreateSchema = LoopsCreateBody
+
+const LoopsCreateSchemaExecute = z.strictObject({
+ confirmation_hash: z
+ .string()
+ .describe('The confirmation_hash returned by the matching -prepare tool. Pass it back verbatim.'),
+ confirmation: z.string().describe('The literal string "confirm", typed by the user in chat. Required to proceed.'),
+})
+
+const loopsCreatePrepare = (): ToolBase => ({
+ name: 'loops-create-prepare',
+ schema: LoopsCreateSchema,
+ handler: async (context: Context, params: z.infer) => {
+ const __runtime = getConfirmedActionRuntime()
+ const __scopeProjectId = await context.stateManager.getProjectId()
+ return await prepareConfirmedAction(context, {
+ args: params,
+ purpose: 'loops-create',
+ actionLabel: 'create loop',
+ messageTemplate:
+ "About to create the loop '{name}', a persistent automation that will run unattended with your GitHub and connector access whenever its triggers fire. Reply 'confirm' to create it.\n",
+ codec: __runtime.codec,
+ boundScope: { projectId: String(__scopeProjectId) },
+ })
+ },
+})
+
+const loopsCreateExecute = (): ToolBase => ({
+ name: 'loops-create-execute',
+ schema: LoopsCreateSchemaExecute,
+ handler: async (context: Context, confirmationParams: z.infer) => {
+ const __runtime = getConfirmedActionRuntime()
+ const __scopeProjectId = await context.stateManager.getProjectId()
+ const __guard = await executeConfirmedAction>(context, {
+ incomingArgs: confirmationParams,
+ purpose: 'loops-create',
+ codec: __runtime.codec,
+ ledger: __runtime.ledger,
+ expectedScope: { projectId: String(__scopeProjectId) },
+ })
+ if (!__guard.ok) {
+ return __guard.result as never
+ }
+ const params = __guard.verifiedArgs
+ const projectId = __scopeProjectId
+ const body: Record = {}
+ if (params.name !== undefined) {
+ body['name'] = params.name
+ }
+ if (params.description !== undefined) {
+ body['description'] = params.description
+ }
+ if (params.take_ownership !== undefined) {
+ body['take_ownership'] = params.take_ownership
+ }
+ if (params.visibility !== undefined) {
+ body['visibility'] = params.visibility
+ }
+ if (params.instructions !== undefined) {
+ body['instructions'] = params.instructions
+ }
+ if (params.runtime_adapter !== undefined) {
+ body['runtime_adapter'] = params.runtime_adapter
+ }
+ if (params.model !== undefined) {
+ body['model'] = params.model
+ }
+ if (params.reasoning_effort !== undefined) {
+ body['reasoning_effort'] = params.reasoning_effort
+ }
+ if (params.repositories !== undefined) {
+ body['repositories'] = params.repositories
+ }
+ if (params.sandbox_environment !== undefined) {
+ body['sandbox_environment'] = params.sandbox_environment
+ }
+ if (params.enabled !== undefined) {
+ body['enabled'] = params.enabled
+ }
+ if (params.overlap_policy !== undefined) {
+ body['overlap_policy'] = params.overlap_policy
+ }
+ if (params.behaviors !== undefined) {
+ body['behaviors'] = params.behaviors
+ }
+ if (params.connectors !== undefined) {
+ body['connectors'] = params.connectors
+ }
+ if (params.notifications !== undefined) {
+ body['notifications'] = params.notifications
+ }
+ if (params.context_target !== undefined) {
+ body['context_target'] = params.context_target
+ }
+ if (params.triggers !== undefined) {
+ body['triggers'] = params.triggers
+ }
+ const result = await context.api.request({
+ method: 'POST',
+ path: `/api/projects/${encodeURIComponent(String(projectId))}/loops/`,
+ body,
+ })
+ return result
+ },
+})
+
+const LoopsDestroySchema = LoopsDestroyParams.omit({ project_id: true })
+
+const loopsDestroy = (): ToolBase => ({
+ name: 'loops-destroy',
+ schema: LoopsDestroySchema,
+ handler: async (context: Context, params: z.infer) => {
+ const projectId = await context.stateManager.getProjectId()
+ const result = await context.api.request({
+ method: 'DELETE',
+ path: `/api/projects/${encodeURIComponent(String(projectId))}/loops/${encodeURIComponent(String(params.id))}/`,
+ })
+ return result
+ },
+})
+
+const LoopsListSchema = LoopsListQueryParams
+
+const loopsList = (): ToolBase> => ({
+ name: 'loops-list',
+ schema: LoopsListSchema,
+ handler: async (context: Context, params: z.infer) => {
+ const projectId = await context.stateManager.getProjectId()
+ const result = await context.api.request({
+ method: 'GET',
+ path: `/api/projects/${encodeURIComponent(String(projectId))}/loops/`,
+ query: {
+ limit: params.limit,
+ offset: params.offset,
+ },
+ })
+ return await withPostHogUrl(context, result, '/tasks')
+ },
+})
+
+const LoopsPartialUpdateSchema = LoopsPartialUpdateParams.omit({ project_id: true }).extend(
+ LoopsPartialUpdateBody.shape
+)
+
+const loopsPartialUpdate = (): ToolBase => ({
+ name: 'loops-partial-update',
+ schema: LoopsPartialUpdateSchema,
+ handler: async (context: Context, params: z.infer) => {
+ const projectId = await context.stateManager.getProjectId()
+ const body: Record = {}
+ if (params.name !== undefined) {
+ body['name'] = params.name
+ }
+ if (params.description !== undefined) {
+ body['description'] = params.description
+ }
+ if (params.take_ownership !== undefined) {
+ body['take_ownership'] = params.take_ownership
+ }
+ if (params.visibility !== undefined) {
+ body['visibility'] = params.visibility
+ }
+ if (params.instructions !== undefined) {
+ body['instructions'] = params.instructions
+ }
+ if (params.runtime_adapter !== undefined) {
+ body['runtime_adapter'] = params.runtime_adapter
+ }
+ if (params.model !== undefined) {
+ body['model'] = params.model
+ }
+ if (params.reasoning_effort !== undefined) {
+ body['reasoning_effort'] = params.reasoning_effort
+ }
+ if (params.repositories !== undefined) {
+ body['repositories'] = params.repositories
+ }
+ if (params.sandbox_environment !== undefined) {
+ body['sandbox_environment'] = params.sandbox_environment
+ }
+ if (params.enabled !== undefined) {
+ body['enabled'] = params.enabled
+ }
+ if (params.overlap_policy !== undefined) {
+ body['overlap_policy'] = params.overlap_policy
+ }
+ if (params.behaviors !== undefined) {
+ body['behaviors'] = params.behaviors
+ }
+ if (params.connectors !== undefined) {
+ body['connectors'] = params.connectors
+ }
+ if (params.notifications !== undefined) {
+ body['notifications'] = params.notifications
+ }
+ if (params.context_target !== undefined) {
+ body['context_target'] = params.context_target
+ }
+ if (params.triggers !== undefined) {
+ body['triggers'] = params.triggers
+ }
+ const result = await context.api.request({
+ method: 'PATCH',
+ path: `/api/projects/${encodeURIComponent(String(projectId))}/loops/${encodeURIComponent(String(params.id))}/`,
+ body,
+ })
+ return result
+ },
+})
+
+const LoopsPreviewCreateSchema = LoopsPreviewCreateParams.omit({ project_id: true }).extend(
+ LoopsPreviewCreateBody.shape
+)
+
+const loopsPreviewCreate = (): ToolBase => ({
+ name: 'loops-preview-create',
+ schema: LoopsPreviewCreateSchema,
+ handler: async (context: Context, params: z.infer) => {
+ const projectId = await context.stateManager.getProjectId()
+ const body: Record = {}
+ if (params.trigger_type !== undefined) {
+ body['trigger_type'] = params.trigger_type
+ }
+ if (params.payload !== undefined) {
+ body['payload'] = params.payload
+ }
+ const result = await context.api.request({
+ method: 'POST',
+ path: `/api/projects/${encodeURIComponent(String(projectId))}/loops/${encodeURIComponent(String(params.id))}/preview/`,
+ body,
+ })
+ return result
+ },
+})
+
+const LoopsRetrieveSchema = LoopsRetrieveParams.omit({ project_id: true })
+
+const loopsRetrieve = (): ToolBase> => ({
+ name: 'loops-retrieve',
+ schema: LoopsRetrieveSchema,
+ handler: async (context: Context, params: z.infer) => {
+ const projectId = await context.stateManager.getProjectId()
+ const result = await context.api.request({
+ method: 'GET',
+ path: `/api/projects/${encodeURIComponent(String(projectId))}/loops/${encodeURIComponent(String(params.id))}/`,
+ })
+ return await withPostHogUrl(context, result, `/tasks/${result.id}`)
+ },
+})
+
+const LoopsRunCreateSchema = LoopsRunCreateParams.omit({ project_id: true })
+
+const loopsRunCreate = (): ToolBase => ({
+ name: 'loops-run-create',
+ schema: LoopsRunCreateSchema,
+ handler: async (context: Context, params: z.infer) => {
+ const projectId = await context.stateManager.getProjectId()
+ const result = await context.api.request({
+ method: 'POST',
+ path: `/api/projects/${encodeURIComponent(String(projectId))}/loops/${encodeURIComponent(String(params.id))}/run/`,
+ })
+ return result
+ },
+})
+
+const LoopsRunsRetrieveSchema = LoopsRunsRetrieveParams.omit({ project_id: true }).extend(
+ LoopsRunsRetrieveQueryParams.shape
+)
+
+const loopsRunsRetrieve = (): ToolBase> => ({
+ name: 'loops-runs-retrieve',
+ schema: LoopsRunsRetrieveSchema,
+ handler: async (context: Context, params: z.infer) => {
+ const projectId = await context.stateManager.getProjectId()
+ const result = await context.api.request({
+ method: 'GET',
+ path: `/api/projects/${encodeURIComponent(String(projectId))}/loops/${encodeURIComponent(String(params.id))}/runs/`,
+ query: {
+ cursor: params.cursor,
+ limit: params.limit,
+ },
+ })
+ return await withPostHogUrl(
+ context,
+ {
+ ...result,
+ results: await Promise.all(
+ (result.results ?? []).map((item) => withPostHogUrl(context, item, `/tasks/${item.id}/runs`))
+ ),
+ },
+ '/tasks'
+ )
+ },
+})
+
const TasksCreateSchema = TasksCreateBody.omit({
title_manually_set: true,
origin_product: true,
@@ -245,6 +557,15 @@ const tasksRunsSessionLogsRetrieve = (): ToolBase ToolBase> = {
+ 'loops-create-prepare': loopsCreatePrepare,
+ 'loops-create-execute': loopsCreateExecute,
+ 'loops-destroy': loopsDestroy,
+ 'loops-list': loopsList,
+ 'loops-partial-update': loopsPartialUpdate,
+ 'loops-preview-create': loopsPreviewCreate,
+ 'loops-retrieve': loopsRetrieve,
+ 'loops-run-create': loopsRunCreate,
+ 'loops-runs-retrieve': loopsRunsRetrieve,
'tasks-create': tasksCreate,
'tasks-list': tasksList,
'tasks-retrieve': tasksRetrieve,
diff --git a/services/mcp/src/tools/index.ts b/services/mcp/src/tools/index.ts
index 3531a8e6ba8c..70f69095bde7 100644
--- a/services/mcp/src/tools/index.ts
+++ b/services/mcp/src/tools/index.ts
@@ -18,6 +18,8 @@ import submitFeedback from './feedback/submit'
import { GENERATED_TOOL_MAP } from './generated'
// Insights
import queryInsight from './insights/query'
+
+import loopsReview from './loops/loopsReview'
// Links (utility — builds canonical app URLs from the frontend's route table)
import generateAppUrl from './links/generate-app-url'
// Notebooks (edit is hand-written — generated CRUD lives in generated/notebooks.ts)
@@ -91,6 +93,7 @@ export const TOOL_MAP: Record ToolBase> = {
// Debug
'debug-mcp-ui-apps': debugMcpUiApps,
+ 'loops-review': loopsReview,
// Feedback
'agent-feedback': submitFeedback,
diff --git a/services/mcp/src/tools/loops/loopsReview.ts b/services/mcp/src/tools/loops/loopsReview.ts
new file mode 100644
index 000000000000..477240fba39e
--- /dev/null
+++ b/services/mcp/src/tools/loops/loopsReview.ts
@@ -0,0 +1,24 @@
+import type { z } from 'zod'
+
+import { LoopsCreateBody } from '@/generated/tasks/api'
+import { withUiApp } from '@/resources/ui-apps'
+import type { Context, ToolBase } from '@/tools/types'
+
+// The review card's input is exactly the `loops-create` body, so the card's "Create loop"
+// button can forward the reviewed config unchanged. This tool doesn't write anything — it
+// echoes the config back so the UI app can render it for confirmation.
+const schema = LoopsCreateBody
+
+type Params = z.infer
+
+export const loopsReviewHandler: ToolBase['handler'] = async (
+ _context: Context,
+ params: Params
+) => params
+
+export default (): ToolBase =>
+ withUiApp('loops-review', {
+ name: 'loops-review',
+ schema,
+ handler: loopsReviewHandler,
+ })
diff --git a/services/mcp/src/ui-apps/apps/loops-review.tsx b/services/mcp/src/ui-apps/apps/loops-review.tsx
new file mode 100644
index 000000000000..8c6c2eabba06
--- /dev/null
+++ b/services/mcp/src/ui-apps/apps/loops-review.tsx
@@ -0,0 +1,78 @@
+import '../styles/tailwind.css'
+
+import type { App } from '@modelcontextprotocol/ext-apps'
+import { useCallback, useState } from 'react'
+import { createRoot } from 'react-dom/client'
+
+import { LoopReviewView, type LoopReviewData, type LoopReviewState } from 'products/tasks/mcp/apps'
+
+import { AppWrapper } from '../components/AppWrapper'
+
+function LoopReviewApp(): JSX.Element {
+ return (
+ appName="PostHog Loop Review">
+ {({ data, app }) => }
+
+ )
+}
+
+function LoopReviewContent({ data, app }: { data: LoopReviewData; app: App | null }): JSX.Element {
+ const [state, setState] = useState({ loading: false, error: null, createdName: null })
+
+ const handleCreate = useCallback(async (): Promise => {
+ if (!app) {
+ setState({
+ loading: false,
+ error: 'Creating loops is not available in this host. Ask the agent to create it in chat.',
+ createdName: null,
+ })
+ return
+ }
+ setState({ loading: true, error: null, createdName: null })
+ try {
+ // `loops-create` is a confirmed action (prepare/execute), so an agent can't plant a
+ // persistent loop without an explicit human step. This button IS that step: prepare with
+ // the reviewed config unchanged (`loops-review`'s schema is the `loops-create` body),
+ // then execute with the returned hash — the click supplies the confirmation.
+ const prepared = await app.callServerTool({
+ name: 'loops-create-prepare',
+ arguments: data as Record,
+ })
+ if (prepared.isError) {
+ const message =
+ prepared.content?.find((c): c is { type: 'text'; text: string } => c.type === 'text')?.text ??
+ 'Failed to create the loop.'
+ setState({ loading: false, error: message, createdName: null })
+ return
+ }
+ const confirmationHash = (prepared.structuredContent as { confirmation_hash?: string } | undefined)
+ ?.confirmation_hash
+ if (!confirmationHash) {
+ setState({ loading: false, error: 'Failed to create the loop.', createdName: null })
+ return
+ }
+ const result = await app.callServerTool({
+ name: 'loops-create-execute',
+ arguments: { confirmation_hash: confirmationHash, confirmation: 'confirm' },
+ })
+ if (result.isError) {
+ const message =
+ result.content?.find((c): c is { type: 'text'; text: string } => c.type === 'text')?.text ??
+ 'Failed to create the loop.'
+ setState({ loading: false, error: message, createdName: null })
+ return
+ }
+ setState({ loading: false, error: null, createdName: data.name?.trim() || 'Your loop' })
+ } catch (err) {
+ const message = err instanceof Error ? err.message : String(err)
+ setState({ loading: false, error: message, createdName: null })
+ }
+ }, [app, data])
+
+ return
+}
+
+const container = document.getElementById('root')
+if (container) {
+ createRoot(container).render()
+}
diff --git a/services/mcp/tests/unit/__snapshots__/tool-schemas/loops-create-execute.json b/services/mcp/tests/unit/__snapshots__/tool-schemas/loops-create-execute.json
new file mode 100644
index 000000000000..f9e863b2ae53
--- /dev/null
+++ b/services/mcp/tests/unit/__snapshots__/tool-schemas/loops-create-execute.json
@@ -0,0 +1,16 @@
+{
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
+ "additionalProperties": false,
+ "properties": {
+ "confirmation": {
+ "description": "The literal string \"confirm\", typed by the user in chat. Required to proceed.",
+ "type": "string"
+ },
+ "confirmation_hash": {
+ "description": "The confirmation_hash returned by the matching -prepare tool. Pass it back verbatim.",
+ "type": "string"
+ }
+ },
+ "required": ["confirmation_hash", "confirmation"],
+ "type": "object"
+}
diff --git a/services/mcp/tests/unit/__snapshots__/tool-schemas/loops-create-prepare.json b/services/mcp/tests/unit/__snapshots__/tool-schemas/loops-create-prepare.json
new file mode 100644
index 000000000000..b4a7864bcf42
--- /dev/null
+++ b/services/mcp/tests/unit/__snapshots__/tool-schemas/loops-create-prepare.json
@@ -0,0 +1,312 @@
+{
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
+ "description": "Request body for creating or updating a loop. Field required/default semantics match\nthe `Loop` model; partial updates only touch keys present in the payload.",
+ "properties": {
+ "behaviors": {
+ "description": "PR / CI-follow-up behavior configuration.",
+ "properties": {
+ "create_prs": {
+ "default": false,
+ "description": "Whether the agent may push branches and open PRs. False makes this a report-only loop.",
+ "type": "boolean"
+ },
+ "fix_review_comments": {
+ "default": false,
+ "description": "Whether to automatically address review comments on loop-created PRs.",
+ "type": "boolean"
+ },
+ "max_fix_iterations": {
+ "default": 3,
+ "description": "Ceiling on automatic CI/review-comment fix iterations, capped at 10.",
+ "maximum": 10,
+ "minimum": 0,
+ "type": "number"
+ },
+ "watch_ci": {
+ "default": false,
+ "description": "Whether to watch CI on loop-created PRs and report status.",
+ "type": "boolean"
+ }
+ },
+ "type": "object"
+ },
+ "connectors": {
+ "description": "MCP connector configuration for this loop's runs.",
+ "properties": {
+ "mcp_installation_ids": {
+ "description": "MCP Store installation ids (Slack, Linear, etc.) available to this loop's runs.",
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ },
+ "posthog_mcp_scopes": {
+ "default": "read_only",
+ "description": "Scope of the PostHog MCP access injected into this loop's runs.\n\n* `read_only` - read_only\n* `full` - full",
+ "enum": ["read_only", "full"],
+ "type": "string"
+ }
+ },
+ "type": "object"
+ },
+ "context_target": {
+ "anyOf": [
+ {
+ "properties": {
+ "folder_id": {
+ "description": "Desktop folder id of the context this loop is attached to.",
+ "type": "string"
+ },
+ "name": {
+ "description": "Context (channel) name, used to file runs into its feed.",
+ "maxLength": 128,
+ "type": "string"
+ },
+ "outputs": {
+ "description": "What the loop maintains in this context each run.",
+ "properties": {
+ "canvas_id": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "Id of a canvas in this context the loop keeps up to date each run, or null to maintain none."
+ },
+ "post_to_feed": {
+ "default": false,
+ "description": "Whether each run is filed into the context's feed as a card (sets the run's channel).",
+ "type": "boolean"
+ },
+ "update_context": {
+ "default": false,
+ "description": "Whether each run reads and republishes the context's context.md to reflect the latest state.",
+ "type": "boolean"
+ }
+ },
+ "type": "object"
+ }
+ },
+ "required": ["folder_id", "name"],
+ "type": "object"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "Context (channel) this loop is attached to, or null to detach. Drives feed placement and the context.md / canvas it keeps up to date."
+ },
+ "description": {
+ "default": "",
+ "description": "Free-form description of what this loop does.",
+ "type": "string"
+ },
+ "enabled": {
+ "default": true,
+ "description": "Whether the loop's triggers are active. Pausing disables all triggers.",
+ "type": "boolean"
+ },
+ "instructions": {
+ "description": "The prompt delivered to the agent on every run.",
+ "type": "string"
+ },
+ "model": {
+ "default": "",
+ "description": "LLM model identifier, validated against `runtime_adapter`'s catalog. Leave blank to let PostHog pick a sensible default at run time.",
+ "type": "string"
+ },
+ "name": {
+ "description": "Display name for the loop.",
+ "maxLength": 400,
+ "type": "string"
+ },
+ "notifications": {
+ "description": "Per-channel notification configuration.",
+ "properties": {
+ "email": {
+ "description": "Email notification settings.",
+ "properties": {
+ "enabled": {
+ "default": false,
+ "description": "Whether this channel is active.",
+ "type": "boolean"
+ },
+ "events": {
+ "description": "Event kinds this channel notifies on. One or more of: run_completed, run_failed, pr_created, needs_attention.",
+ "items": {
+ "description": "* `run_completed` - run_completed\n* `run_failed` - run_failed\n* `pr_created` - pr_created\n* `needs_attention` - needs_attention",
+ "enum": ["run_completed", "run_failed", "pr_created", "needs_attention"],
+ "type": "string"
+ },
+ "type": "array"
+ },
+ "params": {
+ "additionalProperties": {},
+ "description": "Channel-specific parameters, e.g. Slack's `integration_id` and `channel`.",
+ "propertyNames": {
+ "type": "string"
+ },
+ "type": "object"
+ }
+ },
+ "type": "object"
+ },
+ "push": {
+ "description": "Push notification settings.",
+ "properties": {
+ "enabled": {
+ "default": false,
+ "description": "Whether this channel is active.",
+ "type": "boolean"
+ },
+ "events": {
+ "description": "Event kinds this channel notifies on. One or more of: run_completed, run_failed, pr_created, needs_attention.",
+ "items": {
+ "description": "* `run_completed` - run_completed\n* `run_failed` - run_failed\n* `pr_created` - pr_created\n* `needs_attention` - needs_attention",
+ "enum": ["run_completed", "run_failed", "pr_created", "needs_attention"],
+ "type": "string"
+ },
+ "type": "array"
+ },
+ "params": {
+ "additionalProperties": {},
+ "description": "Channel-specific parameters, e.g. Slack's `integration_id` and `channel`.",
+ "propertyNames": {
+ "type": "string"
+ },
+ "type": "object"
+ }
+ },
+ "type": "object"
+ },
+ "slack": {
+ "description": "Slack notification settings.",
+ "properties": {
+ "enabled": {
+ "default": false,
+ "description": "Whether this channel is active.",
+ "type": "boolean"
+ },
+ "events": {
+ "description": "Event kinds this channel notifies on. One or more of: run_completed, run_failed, pr_created, needs_attention.",
+ "items": {
+ "description": "* `run_completed` - run_completed\n* `run_failed` - run_failed\n* `pr_created` - pr_created\n* `needs_attention` - needs_attention",
+ "enum": ["run_completed", "run_failed", "pr_created", "needs_attention"],
+ "type": "string"
+ },
+ "type": "array"
+ },
+ "params": {
+ "additionalProperties": {},
+ "description": "Channel-specific parameters, e.g. Slack's `integration_id` and `channel`.",
+ "propertyNames": {
+ "type": "string"
+ },
+ "type": "object"
+ }
+ },
+ "type": "object"
+ }
+ },
+ "type": "object"
+ },
+ "overlap_policy": {
+ "default": "skip",
+ "description": "What happens when a trigger fires while a run is already active: 'skip', 'allow', or 'cancel_previous'.\n\n* `skip` - skip\n* `allow` - allow\n* `cancel_previous` - cancel_previous",
+ "enum": ["skip", "allow", "cancel_previous"],
+ "type": "string"
+ },
+ "reasoning_effort": {
+ "anyOf": [
+ {
+ "description": "* `low` - low\n* `medium` - medium\n* `high` - high\n* `xhigh` - xhigh\n* `max` - max",
+ "enum": ["low", "medium", "high", "xhigh", "max"],
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "Reasoning effort, validated against `runtime_adapter`/`model`'s supported set.\n\n* `low` - low\n* `medium` - medium\n* `high` - high\n* `xhigh` - xhigh\n* `max` - max"
+ },
+ "repositories": {
+ "description": "Repositories this loop operates on, ordered. Capped at 1 until multi-repo execution ships. May be empty for report-only loops.",
+ "items": {
+ "properties": {
+ "full_name": {
+ "description": "Repository in `organization/repo` format, e.g. `posthog/posthog`.",
+ "maxLength": 255,
+ "type": "string"
+ },
+ "github_integration_id": {
+ "description": "GitHub integration id this repository is accessed through.",
+ "type": "number"
+ }
+ },
+ "required": ["github_integration_id", "full_name"],
+ "type": "object"
+ },
+ "maxItems": 1,
+ "type": "array"
+ },
+ "runtime_adapter": {
+ "description": "Runtime adapter: 'claude' or 'codex'.\n\n* `claude` - claude\n* `codex` - codex",
+ "enum": ["claude", "codex"],
+ "type": "string"
+ },
+ "sandbox_environment": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "Sandbox environment carrying encrypted env vars and the network allowlist into every run."
+ },
+ "take_ownership": {
+ "default": false,
+ "description": "On a team loop, claim ownership as part of this update so you can edit identity-bearing config (instructions, model, triggers, ...) that only the owner may change. Ignored on personal loops and on create.",
+ "type": "boolean"
+ },
+ "triggers": {
+ "description": "Full desired trigger list, id-stable: entries with a matching `id` are updated in place, entries without one are created, and existing triggers absent from this list are deleted. Omit the field entirely to leave triggers untouched. At most 25 triggers per loop.",
+ "items": {
+ "properties": {
+ "config": {
+ "description": "Trigger configuration, shape validated per `type`: schedule takes `{cron_expression, timezone}` or `{run_at}` for a one-time run; github takes `{github_integration_id, repository, events, filters}`; api takes no config."
+ },
+ "enabled": {
+ "default": true,
+ "description": "Whether this trigger is active. Disabling pauses only this trigger.",
+ "type": "boolean"
+ },
+ "id": {
+ "description": "Existing trigger id to update in place. Omit to create a new trigger.",
+ "type": "string"
+ },
+ "type": {
+ "description": "Trigger type: `schedule` (cron or one-time), `github` (repo webhook events), or `api` (POST to `trigger/`).\n\n* `schedule` - schedule\n* `github` - github\n* `api` - api",
+ "enum": ["schedule", "github", "api"],
+ "type": "string"
+ }
+ },
+ "required": ["type"],
+ "type": "object"
+ },
+ "type": "array"
+ },
+ "visibility": {
+ "default": "personal",
+ "description": "`personal` (owner-only) or `team` (visible and fireable by any team member).\n\n* `personal` - personal\n* `team` - team",
+ "enum": ["personal", "team"],
+ "type": "string"
+ }
+ },
+ "required": ["name", "instructions", "runtime_adapter"],
+ "type": "object"
+}
diff --git a/services/mcp/tests/unit/__snapshots__/tool-schemas/loops-destroy.json b/services/mcp/tests/unit/__snapshots__/tool-schemas/loops-destroy.json
new file mode 100644
index 000000000000..f9bfd8020ef3
--- /dev/null
+++ b/services/mcp/tests/unit/__snapshots__/tool-schemas/loops-destroy.json
@@ -0,0 +1,10 @@
+{
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
+ "properties": {
+ "id": {
+ "type": "string"
+ }
+ },
+ "required": ["id"],
+ "type": "object"
+}
diff --git a/services/mcp/tests/unit/__snapshots__/tool-schemas/loops-list.json b/services/mcp/tests/unit/__snapshots__/tool-schemas/loops-list.json
new file mode 100644
index 000000000000..8331b796ac73
--- /dev/null
+++ b/services/mcp/tests/unit/__snapshots__/tool-schemas/loops-list.json
@@ -0,0 +1,14 @@
+{
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
+ "properties": {
+ "limit": {
+ "description": "Number of results to return per page.",
+ "type": "number"
+ },
+ "offset": {
+ "description": "The initial index from which to return the results.",
+ "type": "number"
+ }
+ },
+ "type": "object"
+}
diff --git a/services/mcp/tests/unit/__snapshots__/tool-schemas/loops-partial-update.json b/services/mcp/tests/unit/__snapshots__/tool-schemas/loops-partial-update.json
new file mode 100644
index 000000000000..5b94f4817a6b
--- /dev/null
+++ b/services/mcp/tests/unit/__snapshots__/tool-schemas/loops-partial-update.json
@@ -0,0 +1,308 @@
+{
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
+ "properties": {
+ "behaviors": {
+ "description": "PR / CI-follow-up behavior configuration.",
+ "properties": {
+ "create_prs": {
+ "default": false,
+ "description": "Whether the agent may push branches and open PRs. False makes this a report-only loop.",
+ "type": "boolean"
+ },
+ "fix_review_comments": {
+ "default": false,
+ "description": "Whether to automatically address review comments on loop-created PRs.",
+ "type": "boolean"
+ },
+ "max_fix_iterations": {
+ "default": 3,
+ "description": "Ceiling on automatic CI/review-comment fix iterations, capped at 10.",
+ "maximum": 10,
+ "minimum": 0,
+ "type": "number"
+ },
+ "watch_ci": {
+ "default": false,
+ "description": "Whether to watch CI on loop-created PRs and report status.",
+ "type": "boolean"
+ }
+ },
+ "type": "object"
+ },
+ "connectors": {
+ "description": "MCP connector configuration for this loop's runs.",
+ "properties": {
+ "mcp_installation_ids": {
+ "description": "MCP Store installation ids (Slack, Linear, etc.) available to this loop's runs.",
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ },
+ "posthog_mcp_scopes": {
+ "default": "read_only",
+ "description": "Scope of the PostHog MCP access injected into this loop's runs.\n\n* `read_only` - read_only\n* `full` - full",
+ "enum": ["read_only", "full"],
+ "type": "string"
+ }
+ },
+ "type": "object"
+ },
+ "context_target": {
+ "anyOf": [
+ {
+ "properties": {
+ "folder_id": {
+ "description": "Desktop folder id of the context this loop is attached to.",
+ "type": "string"
+ },
+ "name": {
+ "description": "Context (channel) name, used to file runs into its feed.",
+ "maxLength": 128,
+ "type": "string"
+ },
+ "outputs": {
+ "description": "What the loop maintains in this context each run.",
+ "properties": {
+ "canvas_id": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "Id of a canvas in this context the loop keeps up to date each run, or null to maintain none."
+ },
+ "post_to_feed": {
+ "default": false,
+ "description": "Whether each run is filed into the context's feed as a card (sets the run's channel).",
+ "type": "boolean"
+ },
+ "update_context": {
+ "default": false,
+ "description": "Whether each run reads and republishes the context's context.md to reflect the latest state.",
+ "type": "boolean"
+ }
+ },
+ "type": "object"
+ }
+ },
+ "required": ["folder_id", "name"],
+ "type": "object"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "Context (channel) this loop is attached to, or null to detach. Drives feed placement and the context.md / canvas it keeps up to date."
+ },
+ "description": {
+ "description": "Free-form description of what this loop does.",
+ "type": "string"
+ },
+ "enabled": {
+ "description": "Whether the loop's triggers are active. Pausing disables all triggers.",
+ "type": "boolean"
+ },
+ "id": {
+ "type": "string"
+ },
+ "instructions": {
+ "description": "The prompt delivered to the agent on every run.",
+ "type": "string"
+ },
+ "model": {
+ "description": "LLM model identifier, validated against `runtime_adapter`'s catalog. Leave blank to let PostHog pick a sensible default at run time.",
+ "type": "string"
+ },
+ "name": {
+ "description": "Display name for the loop.",
+ "maxLength": 400,
+ "type": "string"
+ },
+ "notifications": {
+ "description": "Per-channel notification configuration.",
+ "properties": {
+ "email": {
+ "description": "Email notification settings.",
+ "properties": {
+ "enabled": {
+ "default": false,
+ "description": "Whether this channel is active.",
+ "type": "boolean"
+ },
+ "events": {
+ "description": "Event kinds this channel notifies on. One or more of: run_completed, run_failed, pr_created, needs_attention.",
+ "items": {
+ "description": "* `run_completed` - run_completed\n* `run_failed` - run_failed\n* `pr_created` - pr_created\n* `needs_attention` - needs_attention",
+ "enum": ["run_completed", "run_failed", "pr_created", "needs_attention"],
+ "type": "string"
+ },
+ "type": "array"
+ },
+ "params": {
+ "additionalProperties": {},
+ "description": "Channel-specific parameters, e.g. Slack's `integration_id` and `channel`.",
+ "propertyNames": {
+ "type": "string"
+ },
+ "type": "object"
+ }
+ },
+ "type": "object"
+ },
+ "push": {
+ "description": "Push notification settings.",
+ "properties": {
+ "enabled": {
+ "default": false,
+ "description": "Whether this channel is active.",
+ "type": "boolean"
+ },
+ "events": {
+ "description": "Event kinds this channel notifies on. One or more of: run_completed, run_failed, pr_created, needs_attention.",
+ "items": {
+ "description": "* `run_completed` - run_completed\n* `run_failed` - run_failed\n* `pr_created` - pr_created\n* `needs_attention` - needs_attention",
+ "enum": ["run_completed", "run_failed", "pr_created", "needs_attention"],
+ "type": "string"
+ },
+ "type": "array"
+ },
+ "params": {
+ "additionalProperties": {},
+ "description": "Channel-specific parameters, e.g. Slack's `integration_id` and `channel`.",
+ "propertyNames": {
+ "type": "string"
+ },
+ "type": "object"
+ }
+ },
+ "type": "object"
+ },
+ "slack": {
+ "description": "Slack notification settings.",
+ "properties": {
+ "enabled": {
+ "default": false,
+ "description": "Whether this channel is active.",
+ "type": "boolean"
+ },
+ "events": {
+ "description": "Event kinds this channel notifies on. One or more of: run_completed, run_failed, pr_created, needs_attention.",
+ "items": {
+ "description": "* `run_completed` - run_completed\n* `run_failed` - run_failed\n* `pr_created` - pr_created\n* `needs_attention` - needs_attention",
+ "enum": ["run_completed", "run_failed", "pr_created", "needs_attention"],
+ "type": "string"
+ },
+ "type": "array"
+ },
+ "params": {
+ "additionalProperties": {},
+ "description": "Channel-specific parameters, e.g. Slack's `integration_id` and `channel`.",
+ "propertyNames": {
+ "type": "string"
+ },
+ "type": "object"
+ }
+ },
+ "type": "object"
+ }
+ },
+ "type": "object"
+ },
+ "overlap_policy": {
+ "description": "What happens when a trigger fires while a run is already active: 'skip', 'allow', or 'cancel_previous'.\n\n* `skip` - skip\n* `allow` - allow\n* `cancel_previous` - cancel_previous",
+ "enum": ["skip", "allow", "cancel_previous"],
+ "type": "string"
+ },
+ "reasoning_effort": {
+ "anyOf": [
+ {
+ "description": "* `low` - low\n* `medium` - medium\n* `high` - high\n* `xhigh` - xhigh\n* `max` - max",
+ "enum": ["low", "medium", "high", "xhigh", "max"],
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "Reasoning effort, validated against `runtime_adapter`/`model`'s supported set.\n\n* `low` - low\n* `medium` - medium\n* `high` - high\n* `xhigh` - xhigh\n* `max` - max"
+ },
+ "repositories": {
+ "description": "Repositories this loop operates on, ordered. Capped at 1 until multi-repo execution ships. May be empty for report-only loops.",
+ "items": {
+ "properties": {
+ "full_name": {
+ "description": "Repository in `organization/repo` format, e.g. `posthog/posthog`.",
+ "maxLength": 255,
+ "type": "string"
+ },
+ "github_integration_id": {
+ "description": "GitHub integration id this repository is accessed through.",
+ "type": "number"
+ }
+ },
+ "required": ["github_integration_id", "full_name"],
+ "type": "object"
+ },
+ "maxItems": 1,
+ "type": "array"
+ },
+ "runtime_adapter": {
+ "description": "Runtime adapter: 'claude' or 'codex'.\n\n* `claude` - claude\n* `codex` - codex",
+ "enum": ["claude", "codex"],
+ "type": "string"
+ },
+ "sandbox_environment": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "Sandbox environment carrying encrypted env vars and the network allowlist into every run."
+ },
+ "take_ownership": {
+ "description": "On a team loop, claim ownership as part of this update so you can edit identity-bearing config (instructions, model, triggers, ...) that only the owner may change. Ignored on personal loops and on create.",
+ "type": "boolean"
+ },
+ "triggers": {
+ "description": "Full desired trigger list, id-stable: entries with a matching `id` are updated in place, entries without one are created, and existing triggers absent from this list are deleted. Omit the field entirely to leave triggers untouched. At most 25 triggers per loop.",
+ "items": {
+ "properties": {
+ "config": {
+ "description": "Trigger configuration, shape validated per `type`: schedule takes `{cron_expression, timezone}` or `{run_at}` for a one-time run; github takes `{github_integration_id, repository, events, filters}`; api takes no config."
+ },
+ "enabled": {
+ "default": true,
+ "description": "Whether this trigger is active. Disabling pauses only this trigger.",
+ "type": "boolean"
+ },
+ "id": {
+ "description": "Existing trigger id to update in place. Omit to create a new trigger.",
+ "type": "string"
+ },
+ "type": {
+ "description": "Trigger type: `schedule` (cron or one-time), `github` (repo webhook events), or `api` (POST to `trigger/`).\n\n* `schedule` - schedule\n* `github` - github\n* `api` - api",
+ "enum": ["schedule", "github", "api"],
+ "type": "string"
+ }
+ },
+ "required": ["type"],
+ "type": "object"
+ },
+ "type": "array"
+ },
+ "visibility": {
+ "description": "`personal` (owner-only) or `team` (visible and fireable by any team member).\n\n* `personal` - personal\n* `team` - team",
+ "enum": ["personal", "team"],
+ "type": "string"
+ }
+ },
+ "required": ["id"],
+ "type": "object"
+}
diff --git a/services/mcp/tests/unit/__snapshots__/tool-schemas/loops-preview-create.json b/services/mcp/tests/unit/__snapshots__/tool-schemas/loops-preview-create.json
new file mode 100644
index 000000000000..52c27d74cf7e
--- /dev/null
+++ b/services/mcp/tests/unit/__snapshots__/tool-schemas/loops-preview-create.json
@@ -0,0 +1,19 @@
+{
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
+ "properties": {
+ "id": {
+ "type": "string"
+ },
+ "payload": {
+ "description": "Sample trigger payload, e.g. a GitHub webhook body or an API trigger body, to render into context."
+ },
+ "trigger_type": {
+ "default": "schedule",
+ "description": "Trigger type to simulate. Defaults to a synthetic schedule fire.\n\n* `schedule` - schedule\n* `github` - github\n* `api` - api",
+ "enum": ["schedule", "github", "api"],
+ "type": "string"
+ }
+ },
+ "required": ["id"],
+ "type": "object"
+}
diff --git a/services/mcp/tests/unit/__snapshots__/tool-schemas/loops-retrieve.json b/services/mcp/tests/unit/__snapshots__/tool-schemas/loops-retrieve.json
new file mode 100644
index 000000000000..f9bfd8020ef3
--- /dev/null
+++ b/services/mcp/tests/unit/__snapshots__/tool-schemas/loops-retrieve.json
@@ -0,0 +1,10 @@
+{
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
+ "properties": {
+ "id": {
+ "type": "string"
+ }
+ },
+ "required": ["id"],
+ "type": "object"
+}
diff --git a/services/mcp/tests/unit/__snapshots__/tool-schemas/loops-review.json b/services/mcp/tests/unit/__snapshots__/tool-schemas/loops-review.json
new file mode 100644
index 000000000000..b4a7864bcf42
--- /dev/null
+++ b/services/mcp/tests/unit/__snapshots__/tool-schemas/loops-review.json
@@ -0,0 +1,312 @@
+{
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
+ "description": "Request body for creating or updating a loop. Field required/default semantics match\nthe `Loop` model; partial updates only touch keys present in the payload.",
+ "properties": {
+ "behaviors": {
+ "description": "PR / CI-follow-up behavior configuration.",
+ "properties": {
+ "create_prs": {
+ "default": false,
+ "description": "Whether the agent may push branches and open PRs. False makes this a report-only loop.",
+ "type": "boolean"
+ },
+ "fix_review_comments": {
+ "default": false,
+ "description": "Whether to automatically address review comments on loop-created PRs.",
+ "type": "boolean"
+ },
+ "max_fix_iterations": {
+ "default": 3,
+ "description": "Ceiling on automatic CI/review-comment fix iterations, capped at 10.",
+ "maximum": 10,
+ "minimum": 0,
+ "type": "number"
+ },
+ "watch_ci": {
+ "default": false,
+ "description": "Whether to watch CI on loop-created PRs and report status.",
+ "type": "boolean"
+ }
+ },
+ "type": "object"
+ },
+ "connectors": {
+ "description": "MCP connector configuration for this loop's runs.",
+ "properties": {
+ "mcp_installation_ids": {
+ "description": "MCP Store installation ids (Slack, Linear, etc.) available to this loop's runs.",
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ },
+ "posthog_mcp_scopes": {
+ "default": "read_only",
+ "description": "Scope of the PostHog MCP access injected into this loop's runs.\n\n* `read_only` - read_only\n* `full` - full",
+ "enum": ["read_only", "full"],
+ "type": "string"
+ }
+ },
+ "type": "object"
+ },
+ "context_target": {
+ "anyOf": [
+ {
+ "properties": {
+ "folder_id": {
+ "description": "Desktop folder id of the context this loop is attached to.",
+ "type": "string"
+ },
+ "name": {
+ "description": "Context (channel) name, used to file runs into its feed.",
+ "maxLength": 128,
+ "type": "string"
+ },
+ "outputs": {
+ "description": "What the loop maintains in this context each run.",
+ "properties": {
+ "canvas_id": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "Id of a canvas in this context the loop keeps up to date each run, or null to maintain none."
+ },
+ "post_to_feed": {
+ "default": false,
+ "description": "Whether each run is filed into the context's feed as a card (sets the run's channel).",
+ "type": "boolean"
+ },
+ "update_context": {
+ "default": false,
+ "description": "Whether each run reads and republishes the context's context.md to reflect the latest state.",
+ "type": "boolean"
+ }
+ },
+ "type": "object"
+ }
+ },
+ "required": ["folder_id", "name"],
+ "type": "object"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "Context (channel) this loop is attached to, or null to detach. Drives feed placement and the context.md / canvas it keeps up to date."
+ },
+ "description": {
+ "default": "",
+ "description": "Free-form description of what this loop does.",
+ "type": "string"
+ },
+ "enabled": {
+ "default": true,
+ "description": "Whether the loop's triggers are active. Pausing disables all triggers.",
+ "type": "boolean"
+ },
+ "instructions": {
+ "description": "The prompt delivered to the agent on every run.",
+ "type": "string"
+ },
+ "model": {
+ "default": "",
+ "description": "LLM model identifier, validated against `runtime_adapter`'s catalog. Leave blank to let PostHog pick a sensible default at run time.",
+ "type": "string"
+ },
+ "name": {
+ "description": "Display name for the loop.",
+ "maxLength": 400,
+ "type": "string"
+ },
+ "notifications": {
+ "description": "Per-channel notification configuration.",
+ "properties": {
+ "email": {
+ "description": "Email notification settings.",
+ "properties": {
+ "enabled": {
+ "default": false,
+ "description": "Whether this channel is active.",
+ "type": "boolean"
+ },
+ "events": {
+ "description": "Event kinds this channel notifies on. One or more of: run_completed, run_failed, pr_created, needs_attention.",
+ "items": {
+ "description": "* `run_completed` - run_completed\n* `run_failed` - run_failed\n* `pr_created` - pr_created\n* `needs_attention` - needs_attention",
+ "enum": ["run_completed", "run_failed", "pr_created", "needs_attention"],
+ "type": "string"
+ },
+ "type": "array"
+ },
+ "params": {
+ "additionalProperties": {},
+ "description": "Channel-specific parameters, e.g. Slack's `integration_id` and `channel`.",
+ "propertyNames": {
+ "type": "string"
+ },
+ "type": "object"
+ }
+ },
+ "type": "object"
+ },
+ "push": {
+ "description": "Push notification settings.",
+ "properties": {
+ "enabled": {
+ "default": false,
+ "description": "Whether this channel is active.",
+ "type": "boolean"
+ },
+ "events": {
+ "description": "Event kinds this channel notifies on. One or more of: run_completed, run_failed, pr_created, needs_attention.",
+ "items": {
+ "description": "* `run_completed` - run_completed\n* `run_failed` - run_failed\n* `pr_created` - pr_created\n* `needs_attention` - needs_attention",
+ "enum": ["run_completed", "run_failed", "pr_created", "needs_attention"],
+ "type": "string"
+ },
+ "type": "array"
+ },
+ "params": {
+ "additionalProperties": {},
+ "description": "Channel-specific parameters, e.g. Slack's `integration_id` and `channel`.",
+ "propertyNames": {
+ "type": "string"
+ },
+ "type": "object"
+ }
+ },
+ "type": "object"
+ },
+ "slack": {
+ "description": "Slack notification settings.",
+ "properties": {
+ "enabled": {
+ "default": false,
+ "description": "Whether this channel is active.",
+ "type": "boolean"
+ },
+ "events": {
+ "description": "Event kinds this channel notifies on. One or more of: run_completed, run_failed, pr_created, needs_attention.",
+ "items": {
+ "description": "* `run_completed` - run_completed\n* `run_failed` - run_failed\n* `pr_created` - pr_created\n* `needs_attention` - needs_attention",
+ "enum": ["run_completed", "run_failed", "pr_created", "needs_attention"],
+ "type": "string"
+ },
+ "type": "array"
+ },
+ "params": {
+ "additionalProperties": {},
+ "description": "Channel-specific parameters, e.g. Slack's `integration_id` and `channel`.",
+ "propertyNames": {
+ "type": "string"
+ },
+ "type": "object"
+ }
+ },
+ "type": "object"
+ }
+ },
+ "type": "object"
+ },
+ "overlap_policy": {
+ "default": "skip",
+ "description": "What happens when a trigger fires while a run is already active: 'skip', 'allow', or 'cancel_previous'.\n\n* `skip` - skip\n* `allow` - allow\n* `cancel_previous` - cancel_previous",
+ "enum": ["skip", "allow", "cancel_previous"],
+ "type": "string"
+ },
+ "reasoning_effort": {
+ "anyOf": [
+ {
+ "description": "* `low` - low\n* `medium` - medium\n* `high` - high\n* `xhigh` - xhigh\n* `max` - max",
+ "enum": ["low", "medium", "high", "xhigh", "max"],
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "Reasoning effort, validated against `runtime_adapter`/`model`'s supported set.\n\n* `low` - low\n* `medium` - medium\n* `high` - high\n* `xhigh` - xhigh\n* `max` - max"
+ },
+ "repositories": {
+ "description": "Repositories this loop operates on, ordered. Capped at 1 until multi-repo execution ships. May be empty for report-only loops.",
+ "items": {
+ "properties": {
+ "full_name": {
+ "description": "Repository in `organization/repo` format, e.g. `posthog/posthog`.",
+ "maxLength": 255,
+ "type": "string"
+ },
+ "github_integration_id": {
+ "description": "GitHub integration id this repository is accessed through.",
+ "type": "number"
+ }
+ },
+ "required": ["github_integration_id", "full_name"],
+ "type": "object"
+ },
+ "maxItems": 1,
+ "type": "array"
+ },
+ "runtime_adapter": {
+ "description": "Runtime adapter: 'claude' or 'codex'.\n\n* `claude` - claude\n* `codex` - codex",
+ "enum": ["claude", "codex"],
+ "type": "string"
+ },
+ "sandbox_environment": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "Sandbox environment carrying encrypted env vars and the network allowlist into every run."
+ },
+ "take_ownership": {
+ "default": false,
+ "description": "On a team loop, claim ownership as part of this update so you can edit identity-bearing config (instructions, model, triggers, ...) that only the owner may change. Ignored on personal loops and on create.",
+ "type": "boolean"
+ },
+ "triggers": {
+ "description": "Full desired trigger list, id-stable: entries with a matching `id` are updated in place, entries without one are created, and existing triggers absent from this list are deleted. Omit the field entirely to leave triggers untouched. At most 25 triggers per loop.",
+ "items": {
+ "properties": {
+ "config": {
+ "description": "Trigger configuration, shape validated per `type`: schedule takes `{cron_expression, timezone}` or `{run_at}` for a one-time run; github takes `{github_integration_id, repository, events, filters}`; api takes no config."
+ },
+ "enabled": {
+ "default": true,
+ "description": "Whether this trigger is active. Disabling pauses only this trigger.",
+ "type": "boolean"
+ },
+ "id": {
+ "description": "Existing trigger id to update in place. Omit to create a new trigger.",
+ "type": "string"
+ },
+ "type": {
+ "description": "Trigger type: `schedule` (cron or one-time), `github` (repo webhook events), or `api` (POST to `trigger/`).\n\n* `schedule` - schedule\n* `github` - github\n* `api` - api",
+ "enum": ["schedule", "github", "api"],
+ "type": "string"
+ }
+ },
+ "required": ["type"],
+ "type": "object"
+ },
+ "type": "array"
+ },
+ "visibility": {
+ "default": "personal",
+ "description": "`personal` (owner-only) or `team` (visible and fireable by any team member).\n\n* `personal` - personal\n* `team` - team",
+ "enum": ["personal", "team"],
+ "type": "string"
+ }
+ },
+ "required": ["name", "instructions", "runtime_adapter"],
+ "type": "object"
+}
diff --git a/services/mcp/tests/unit/__snapshots__/tool-schemas/loops-run-create.json b/services/mcp/tests/unit/__snapshots__/tool-schemas/loops-run-create.json
new file mode 100644
index 000000000000..f9bfd8020ef3
--- /dev/null
+++ b/services/mcp/tests/unit/__snapshots__/tool-schemas/loops-run-create.json
@@ -0,0 +1,10 @@
+{
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
+ "properties": {
+ "id": {
+ "type": "string"
+ }
+ },
+ "required": ["id"],
+ "type": "object"
+}
diff --git a/services/mcp/tests/unit/__snapshots__/tool-schemas/loops-runs-retrieve.json b/services/mcp/tests/unit/__snapshots__/tool-schemas/loops-runs-retrieve.json
new file mode 100644
index 000000000000..a3716f7276d5
--- /dev/null
+++ b/services/mcp/tests/unit/__snapshots__/tool-schemas/loops-runs-retrieve.json
@@ -0,0 +1,22 @@
+{
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
+ "properties": {
+ "cursor": {
+ "description": "Opaque pagination cursor from a previous response's `next_cursor`.",
+ "minLength": 1,
+ "type": "string"
+ },
+ "id": {
+ "type": "string"
+ },
+ "limit": {
+ "default": 50,
+ "description": "Max results per page (default 50, max 100).",
+ "maximum": 100,
+ "minimum": 1,
+ "type": "number"
+ }
+ },
+ "required": ["id"],
+ "type": "object"
+}
diff --git a/services/mcp/tests/unit/tool-filtering.test.ts b/services/mcp/tests/unit/tool-filtering.test.ts
index 105843cc9545..c2ab1fe94560 100644
--- a/services/mcp/tests/unit/tool-filtering.test.ts
+++ b/services/mcp/tests/unit/tool-filtering.test.ts
@@ -818,9 +818,20 @@ describe('Tool Filtering - Feature Flags', () => {
'engineering-analytics',
'stamphog',
'product-data-catalog',
+ 'loops',
])
)
- expect(flags).toHaveLength(22)
+ expect(flags).toHaveLength(23)
+ })
+
+ it('every loops tool is gated on the loops flag', () => {
+ // Guards against a loops tool (hand-written like loops-review, or generated)
+ // shipping without the gate and leaking the unreleased surface pre-rollout.
+ const loopsTools = Object.entries(getToolDefinitions()).filter(([name]) => name.startsWith('loops-'))
+ expect(loopsTools.length).toBeGreaterThan(0)
+ for (const [name, definition] of loopsTools) {
+ expect({ name, feature_flag: definition.feature_flag }).toEqual({ name, feature_flag: 'loops' })
+ }
})
// Exercise the real predicate (toolPassesFlagGate) over hand-rolled entries
diff --git a/services/mcp/tests/unit/tool-schema-snapshots.test.ts b/services/mcp/tests/unit/tool-schema-snapshots.test.ts
index 96023d49880c..37919bcd165b 100644
--- a/services/mcp/tests/unit/tool-schema-snapshots.test.ts
+++ b/services/mcp/tests/unit/tool-schema-snapshots.test.ts
@@ -89,12 +89,13 @@ describe('Tool schema snapshots', () => {
it('snapshots runtime tool schemas', async () => {
const shouldUpdateSnapshots = isSnapshotUpdateAll()
const root = path.resolve(__dirname, '__snapshots__', 'tool-schemas')
- // Enable flag-gated tools we snapshot here: tracing (APM spans), tasks,
+ // Enable flag-gated tools we snapshot here: tracing (APM spans), tasks, loops,
// dashboard-widgets. Other flag-gated tools (logs-alerts, visual-review, etc.) stay off to keep the surface stable.
// agent-feedback is always_available and no longer flag-gated, so it appears regardless.
const featureFlags = {
tracing: true,
tasks: true,
+ loops: true,
'dashboard-widgets': true,
'agent-platform': true,
}
diff --git a/tach.toml b/tach.toml
index bf4a462fe5de..b6bf892b45c8 100644
--- a/tach.toml
+++ b/tach.toml
@@ -719,6 +719,7 @@ depends_on = [
"products.feature_flags",
"products.ai_observability",
"products.mcp_store",
+ "products.notifications",
"products.posthog_ai",
"products.signals",
"products.slack_app",