|
| 1 | +import type { QueryToolInfo, ToolInfo } from '@/lib/instructions' |
| 2 | +import { type InstructionsContext, InstructionsFormatter } from '@/lib/instructions-formatter' |
| 3 | +import { getToolDefinition } from '@/tools/toolDefinitions' |
| 4 | +import type { Tool, ZodObjectAny } from '@/tools/types' |
| 5 | + |
| 6 | +import { EXPERIMENTAL_API_ENV } from './experimental' |
| 7 | + |
| 8 | +const AGENT_HELP_HEADER = `# PostHog API guide for agents |
| 9 | +
|
| 10 | +\`posthog-cli api\` is the agent-first interface to the PostHog API. It exposes the same tool surface as the PostHog MCP server's \`exec\` tool, so the reference below is the canonical guide for interacting with PostHog. Treat it as instructions to follow, not just documentation. |
| 11 | +
|
| 12 | +The command group is experimental: pass \`--experimental\` right after \`api\`, or set \`${EXPERIMENTAL_API_ENV}=1\` in the environment. |
| 13 | +
|
| 14 | +On top of the reference below, the CLI adds: |
| 15 | +
|
| 16 | +- \`posthog-cli api call --dry-run <tool> '<json>'\` — validate input against the tool schema without executing. Use it before any mutation. |
| 17 | +- Destructive tools refuse to run without \`--confirm\`; add it only after verifying the exact target IDs. |
| 18 | +- \`posthog-cli api skill list\` and \`posthog-cli api skill install <skill-id>\` — install PostHog agent skills into \`.agents/skills/\`. |
| 19 | +- \`posthog-cli api agents-md install [--path AGENTS.md]\` — install the PostHog steering snippet into a repository.` |
| 20 | + |
| 21 | +const EXEC_INVOCATION_PATTERN = /posthog:exec\(\{\s*"command":\s*"((?:\\.|[^"\\])*)"\s*\}\)/g |
| 22 | + |
| 23 | +function commandToCliInvocation(command: string): string { |
| 24 | + const braceIndex = command.indexOf('{') |
| 25 | + if (braceIndex === -1) { |
| 26 | + return `posthog-cli api ${command}` |
| 27 | + } |
| 28 | + return `posthog-cli api ${command.slice(0, braceIndex).trimEnd()} '${command.slice(braceIndex)}'` |
| 29 | +} |
| 30 | + |
| 31 | +/** The MCP templates document the exec surface as \`posthog:exec({ "command": "<cmd>" })\` |
| 32 | + * tool calls. The CLI exposes the identical command strings as \`posthog-cli api <cmd>\`, |
| 33 | + * so rewriting invocations (instead of forking the templates) keeps one source of truth. */ |
| 34 | +export function toCliSyntax(text: string): string { |
| 35 | + return text |
| 36 | + .replace(EXEC_INVOCATION_PATTERN, (_match, command: string) => |
| 37 | + commandToCliInvocation(command.replace(/\\"/g, '"')) |
| 38 | + ) |
| 39 | + .replace('### Using the `posthog` tool', '### Using `posthog-cli api`') |
| 40 | + .replace( |
| 41 | + 'Pass CLI-style commands in the `command` parameter for all PostHog interactions.', |
| 42 | + 'Pass CLI-style commands as arguments to `posthog-cli api` for all PostHog interactions.' |
| 43 | + ) |
| 44 | +} |
| 45 | + |
| 46 | +/** Build the full agent-facing guide for \`posthog-cli api --agent-help\` from the same |
| 47 | + * exec-tool templates the MCP server serves, including the tool-domain index and the |
| 48 | + * query-tool catalog derived from the bundled tool registry (no network or auth needed). */ |
| 49 | +export function buildAgentHelp(tools: Tool<ZodObjectAny>[]): string { |
| 50 | + const formatter = new InstructionsFormatter() |
| 51 | + const toolInfos: ToolInfo[] = tools.map((tool) => ({ |
| 52 | + name: tool.name, |
| 53 | + category: getToolDefinition(tool.name).category, |
| 54 | + })) |
| 55 | + const queryTools: QueryToolInfo[] = tools |
| 56 | + .filter((tool) => tool.name.startsWith('query-')) |
| 57 | + .map((tool) => { |
| 58 | + const definition = getToolDefinition(tool.name) |
| 59 | + return { |
| 60 | + name: tool.name, |
| 61 | + title: definition.title, |
| 62 | + ...(definition.system_prompt_hint ? { systemPromptHint: definition.system_prompt_hint } : {}), |
| 63 | + } as QueryToolInfo |
| 64 | + }) |
| 65 | + |
| 66 | + const ctx: InstructionsContext = { guidelines: '', tools: toolInfos, queryTools } |
| 67 | + const sections = [ |
| 68 | + AGENT_HELP_HEADER, |
| 69 | + formatter.buildExecToolDescription(), |
| 70 | + formatter.buildExecCommandReference(ctx, { stripEnvContext: false }), |
| 71 | + ] |
| 72 | + return toCliSyntax(sections.join('\n\n')) |
| 73 | +} |
0 commit comments