Skip to content

: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.

2.5 KB
Raw Blame
/**
 * Abstract, domain-agnostic attached-context shape for the PostHog AI surface. The surface never
 * enumerates entity types — a provider names an arbitrary `type` (e.g. 'insight', 'dashboard',
 * 'trace', 'text') and the block builder renders it as-is.
 */
export interface AttachedContextItem {
    /**
     * Arbitrary resource kind, e.g. 'insight', 'dashboard', 'trace', 'text'. The one reserved value
     * is 'instructions': it renders into the trusted `<posthog_trusted_context>` block the agent is
     * told to follow, so it must only ever carry our own static strings — never interpolated user or
     * ingested data. Every other type renders as untrusted data.
     */
    type: string
    /** Resource identifier — entity id, short_id, $ai_trace_id, … */
    key?: string | number
    /**
     * The id in the item's page URL, when it differs from `key` (a flag's context key is its name, and its page
     * takes the numeric id). Null means the item has no page. Undefined means `key` is the page id.
     */
    pageId?: string | number | null
    /** Optional human-readable label. */
    label?: string
    /**
     * Self-contained HTML the composer shows as an attachment thumbnail above the context chips, in a
     * sandboxed iframe. Display only: it never enters the context blocks, so the agent still fetches the
     * resource by `key`.
     */
    previewHtml?: string
    /** Free-text payload (used when there's no keyed resource, e.g. type 'text'). */
    value?: string
    /** Rendered into the context blocks as usual but never shown as a composer chip (so not dismissable either). */
    hidden?: boolean
    /** Whether the user can dismiss the item from the composer. Defaults to true. */
    dismissible?: boolean
    /**
     * Items sharing a `dismissGroup` are dismissed together: closing any chip in the group also
     * detaches the group's hidden items, so a chip never claims control it doesn't have. Dismissal
     * is recorded against this stable name rather than the dedupe key, which makes it stick for
     * hidden items whose value (and therefore key) changes on every re-registration, e.g. live
     * editor state.
     */
    dismissGroup?: string
}

/** A new chat's picks live under this key until its first send delivers them to the created task. */
export const NEW_CHAT_KEY = ''

/** Stable dedupe key for an attached context item: `${type}:${key ?? value}`. */
export function attachedContextItemKey(item: AttachedContextItem): string {
    return `${item.type}:${item.key ?? item.value ?? ''}`
}