:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
import type { z } from 'zod'
import { PinnedContextSwitchError, wrapError } from '@/lib/errors'
import { buildActiveEnvironmentContextPrompt } from '@/lib/instructions'
import { ProjectSetActiveSchema } from '@/schema/tool-inputs'
import type { CachedOrg, CachedProject, Context, ToolBase } from '@/tools/types'
const schema = ProjectSetActiveSchema
type Params = z.infer<typeof schema>
type Result = { content: Array<{ type: string; text: string }> }
export const setActiveHandler: ToolBase<typeof schema, Result>['handler'] = async (
context: Context,
params: Params
) => {
const { projectId } = params
const projectIdStr = projectId.toString()
// Without a session, the next request applies the pin again. Refuse up front
// rather than report a switch that the next tool call reverts.
const pinned = context.stateManager.pinnedContext
const pinLocksContext = pinned !== undefined && !pinned.sessionScoped
if (pinLocksContext && pinned.pin.projectId && pinned.pin.projectId !== projectIdStr) {
throw new PinnedContextSwitchError(pinned.pin)
}
// Resolve the active org the same way every other org-scoped tool does
// (`getOrgID` falls back to the API-key default and the cached project),
// rather than reading the raw `orgId` cache key which is often unset on the
// first call and would make the org comparison below always look like a switch.
const activeOrgId = await context.stateManager.getOrgID().catch(() => undefined)
const activeOrgLabel = activeOrgId ?? 'unknown'
// Validate before committing the session: only switch to a project the user
// can actually access. Previously the projectId was cached before the fetch,
// so a bad id (or a project the session can't reach) silently "succeeded" and
// every later call failed with an opaque error instead.
const projectResult = await context.api.projects().get({ projectId: projectIdStr })
if (!projectResult.success) {
// Preserve the typed API error as `cause`: a not-found / no-access 404-403
// is a recoverable agent mistake that `handleToolError` should keep out of
// exception tracking, while a genuine 5xx still gets captured.
throw wrapError(
`Could not switch to project ${projectIdStr}: it was not found or you don't have access to it from the active organization (${activeOrgLabel}). ` +
'If the project belongs to a different organization, call `organizations-get` to list your organizations, then `switch-organization` to the one that owns it, and retry. ' +
'Use `projects-get` to see the projects available in the active organization.',
projectResult.error
)
}
const project: CachedProject = projectResult.data
const projectOrgId = project.organization
if (pinLocksContext && pinned.pin.organizationId && projectOrgId && projectOrgId !== pinned.pin.organizationId) {
throw new PinnedContextSwitchError({ organizationId: pinned.pin.organizationId })
}
const orgChanged = Boolean(projectOrgId && projectOrgId !== activeOrgId)
await context.stateManager.setActiveContext({
projectId: projectIdStr,
...(orgChanged ? { orgId: projectOrgId } : {}),
})
await context.cache.set(`cachedProject:${projectIdStr}` as const, project)
await context.cache.set(`cachedProjectFetchedAt:${projectIdStr}` as const, Date.now())
// Keep the active organization consistent with the project we just selected.
// Switching to a project in another organization would otherwise leave
// org-scoped tools pointed at the wrong organization.
let orgId = activeOrgId
let org: CachedOrg | undefined
let switchedOrg = false
if (orgChanged) {
orgId = projectOrgId
// Only a genuine switch if a different org was already active; when no org
// was resolved yet we're just establishing context, not switching away.
switchedOrg = activeOrgId !== undefined
// Fetch the org through the shared resolver so the scoped-token guard
// (which skips the non-project-nested `/api/organizations/{id}/` call the
// backend rejects for project-scoped keys) and org caching stay in one
// place instead of being duplicated here and drifting.
org = await context.stateManager.getCachedOrFetchOrg()
}
// Read the cached org, when we didn't just fetch it, for the metadata block
if (!org && orgId) {
org = (await context.cache.get(`cachedOrg:${orgId}` as const)) as CachedOrg | undefined
}
const orgNote = switchedOrg ? ` (also switched the active organization to ${orgId} to match)` : ''
const integrationKinds = await context.stateManager.getOrFetchIntegrationKinds(projectIdStr).catch(() => undefined)
const metadata = buildActiveEnvironmentContextPrompt(org, project, context.api.publicBaseUrl, {
integrationKinds,
})
const text = metadata
? `Switched to project ${projectId}${orgNote}.\n\nCurrent context:\n${metadata}`
: `Switched to project ${projectId}${orgNote}`
return {
content: [{ type: 'text', text }],
}
}
const tool = (): ToolBase<typeof schema, Result> => ({
name: 'switch-project',
schema,
handler: setActiveHandler,
})
export default tool