@trillboards/cli 0.1.0 → 0.1.1

package/dist/ads-client.d.ts

@@ -0,0 +1,146 @@
+/**
+ * Virtual-screen ad client for the agent-ads surface.
+ *
+ * A "virtual screen" is a developer-owned screen (no partner_id) that rents an
+ * AI-coding-agent's dead-time. The backend serves it through the EARNER + OpenRTB
+ * routes — NOT the partner-device routes the @trillboards/ads-sdk ApiClient is
+ * hardwired to. So this module owns the earner/openrtb calls and reuses the SDK
+ * only where the SDK's method targets a path that works for a partner-less screen
+ * (reportImpression → /v1/partner/impression records cleanly with partner_id=null).
+ *
+ * Endpoints (all grounded in trillboard-api):
+ *   - register   POST /v2/earner/virtual-screen/register   (Bearer user JWT)
+ *   - heartbeat  POST /v2/earner/heartbeat/:screenId        (public)
+ *   - ads        GET  /v2/earner/alot-advertisement-list/:screen_id  (public)
+ *   - player     GET  /openrtb/v1/ima-player/:screenId?tag&did        (billable)
+ *   - event      POST /openrtb/v1/event?adid&event&screenId&deviceId  (public)
+ */
+export interface RegisterResult {
+    screenId: string;
+    deviceId: string;
+    isReRegistration: boolean;
+}
+/**
+ * Register (or idempotently re-register) this install as a virtual screen.
+ * Requires the user JWT. Body: {machineId, name?}. The server keys idempotency on
+ * md5(userMongoId:machineId), so the same machineId+user returns the same screen.
+ */
+export declare function registerVirtualScreen(baseUrl: string, token: string, machineId: string, name: string): Promise<RegisterResult>;
+/**
+ * Keep the virtual screen "online" so GIVT screen-liveness (≤90s) lets the
+ * agent_direct completion bill. Uses the generic OpenRTB heartbeat — the earner
+ * heartbeat (/v2/earner/heartbeat/:id) 404s for virtual screens because the
+ * heartbeatMonitor only tracks physical/registered screens, whereas
+ * /openrtb/v1/heartbeat records liveness for ANY screenId. Public endpoint;
+ * best-effort (never throws), so a transient blip doesn't kill the loop.
+ */
+export declare function sendVirtualScreenHeartbeat(baseUrl: string, screenId: string, deviceId?: string | null): Promise<boolean>;
+export interface VirtualScreenAd {
+    /** Winning/primary web VAST tag URL (data.header_bidding_settings.vast_tag_url). */
+    vastTagUrl: string | null;
+    /** Partner alias for the winning source (variant_name), for telemetry. */
+    variantName: string | null;
+    /** All waterfall fallback tag URLs in priority order (sources[].vast_url). */
+    sources: string[];
+}
+/**
+ * GET /v2/earner/alot-advertisement-list/:screen_id and extract the web VAST tag.
+ *
+ * Response envelope: { status, code, message, data }. The programmatic block lives
+ * at `data.header_bidding_settings` with `vast_tag_url` (the winning tag) and
+ * `vast_waterfall.sources[].vast_url` (fallbacks). Returns nulls when no fill.
+ */
+export declare function fetchVirtualScreenAds(baseUrl: string, screenId: string): Promise<VirtualScreenAd>;
+export interface VirtualScreenTextAd {
+    /** Advertisement mongo id (overlay_advertisements[0].content.id), for telemetry. */
+    adId: string | null;
+    /** Advertiser headline (content.name) — the sponsor line's lede. */
+    name: string | null;
+    /** Optional supporting copy (content.description). */
+    description: string | null;
+    /** Click destination (content.campaign_link) — the CTA URL. */
+    campaignLink: string | null;
+    /** Winning programmatic source alias, for event telemetry. */
+    variantName: string | null;
+}
+/**
+ * GET /v2/earner/alot-advertisement-list/:screen_id and extract the TEXT creative
+ * from the first overlay advertisement. This is the no-browser, in-place surface:
+ * the agent-ads house/paid ad always carries name + campaign_link, so a sponsor
+ * LINE can render right in the agent's dead-time with zero video player.
+ *
+ * Returns null on no-fill (no overlay ad, or no usable headline). Tight default
+ * timeout — the Claude Code hook must stay fast and never block the prompt.
+ */
+export declare function fetchVirtualScreenTextAd(baseUrl: string, screenId: string, timeoutMs?: number): Promise<VirtualScreenTextAd | null>;
+export interface VirtualScreenCreative {
+    /** Chosen format. Server stamps `content.mediaType` (selectCreativeFormat); we fall back to inference. */
+    mediaType: 'text' | 'image' | 'video';
+    adId: string | null;
+    name: string | null;
+    description: string | null;
+    campaignLink: string | null;
+    variantName: string | null;
+    /** Video or image URL (null for text-only). */
+    mediaUrl: string | null;
+    durationSeconds: number | null;
+    /** AdX/programmatic VAST tag (Leg A) when present — opened in a webview/browser. */
+    vastTagUrl: string | null;
+    /**
+     * Hosted IMA-player URL for the programmatic VAST tag (Leg A), pre-built when the tag
+     * is playable (mirrors how the screen app + ads-sdk ProgrammaticPlayer feed the tag to
+     * the Google IMA SDK). The wrapper opens this during dead-time; the wrap's signed pixels
+     * bill via `vast_event`. null when there's no playable programmatic fill.
+     */
+    imaPlayerUrl: string | null;
+    /**
+     * Server-signed agent_direct completion beacon (relative URL). Fire this VERBATIM
+     * (resolved against baseUrl) on play completion — the server minted the `&sig=`,
+     * so it passes VAST_ATTRIBUTION_REQUIRE_SIG where a client-built complete cannot.
+     * null when the server didn't attach one (e.g. an old server, or no-fill).
+     */
+    completeUrl: string | null;
+}
+/**
+ * GET the manifest declaring `?surface_capabilities=…` and return the chosen creative
+ * for whatever the host terminal can render. Forward-compatible: an old server ignores
+ * the param and returns its video/image creative; the new server's `selectCreativeFormat`
+ * honors it and may return text. Returns null on no-fill.
+ */
+export declare function fetchVirtualScreenCreative(baseUrl: string, screenId: string, surfaceCapabilities: string, deviceId?: string | null, timeoutMs?: number): Promise<VirtualScreenCreative | null>;
+/**
+ * Fire the SERVER-SIGNED agent_direct completion beacon on play completion. The
+ * URL (with its `&sig=`) was minted by the serve path, so this passes
+ * VAST_ATTRIBUTION_REQUIRE_SIG — the wrapper never builds or signs the complete
+ * itself. Best-effort, fire-and-forget: never throws, returns true on a 2xx.
+ */
+export declare function reportVirtualScreenCompletion(baseUrl: string, completeUrl: string | null): Promise<boolean>;
+/**
+ * Build the URL-loadable, billable IMA player link. Opening this in a browser
+ * loads the hosted ima-player.js which fires the VAST impression/quartile/complete
+ * pixels (that is the money path — the TTY can't render video).
+ *
+ * The server-side `isAllowedTagUrl` SSRF allowlist gates the `tag` param to known
+ * ad-server hosts (GAM/doubleclick/adipolo/adtelligent/...). A non-allowlisted tag
+ * yields a 400 page, so we surface a clear hint when the tag won't be playable.
+ */
+export declare function buildImaPlayerUrl(baseUrl: string, screenId: string, vastTagUrl: string, deviceId: string | null, variantName?: string | null): string;
+/** Mirror of the server's allowlist so we can warn before printing an unplayable link. */
+export declare function isPlayableTagUrl(vastTagUrl: string): boolean;
+/**
+ * Report a text-ad / programmatic lifecycle event for the virtual screen via the
+ * public OpenRTB event endpoint (the partner programmatic-event route 403s for a
+ * partner-less screen). Best-effort, fire-and-forget; never throws.
+ *
+ * `adid` is required by the endpoint; for synthetic lifecycle events (request,
+ * no_fill) we pass a deterministic synthetic id.
+ */
+export declare function reportTextAdEvent(baseUrl: string, params: {
+    screenId: string;
+    deviceId: string | null;
+    event: string;
+    adid: string;
+    variantName?: string | null;
+}, timeoutMs?: number): Promise<boolean>;
+/** Generate a synthetic per-impression id for text-ad telemetry. */
+export declare function newImpressionId(): string;

package/dist/ads-client.js

@@ -0,0 +1,310 @@
+/**
+ * Virtual-screen ad client for the agent-ads surface.
+ *
+ * A "virtual screen" is a developer-owned screen (no partner_id) that rents an
+ * AI-coding-agent's dead-time. The backend serves it through the EARNER + OpenRTB
+ * routes — NOT the partner-device routes the @trillboards/ads-sdk ApiClient is
+ * hardwired to. So this module owns the earner/openrtb calls and reuses the SDK
+ * only where the SDK's method targets a path that works for a partner-less screen
+ * (reportImpression → /v1/partner/impression records cleanly with partner_id=null).
+ *
+ * Endpoints (all grounded in trillboard-api):
+ *   - register   POST /v2/earner/virtual-screen/register   (Bearer user JWT)
+ *   - heartbeat  POST /v2/earner/heartbeat/:screenId        (public)
+ *   - ads        GET  /v2/earner/alot-advertisement-list/:screen_id  (public)
+ *   - player     GET  /openrtb/v1/ima-player/:screenId?tag&did        (billable)
+ *   - event      POST /openrtb/v1/event?adid&event&screenId&deviceId  (public)
+ */
+import crypto from 'node:crypto';
+import { apiRequest } from './http.js';
+/**
+ * Register (or idempotently re-register) this install as a virtual screen.
+ * Requires the user JWT. Body: {machineId, name?}. The server keys idempotency on
+ * md5(userMongoId:machineId), so the same machineId+user returns the same screen.
+ */
+export async function registerVirtualScreen(baseUrl, token, machineId, name) {
+    const res = (await apiRequest('POST', '/v2/earner/virtual-screen/register', {
+        baseUrl,
+        token,
+        body: { machineId, name },
+    }));
+    const screenId = typeof res.screenId === 'string' ? res.screenId : '';
+    const deviceId = typeof res.deviceId === 'string' ? res.deviceId : '';
+    if (!screenId || !deviceId) {
+        throw new Error('Register response missing screenId/deviceId');
+    }
+    return { screenId, deviceId, isReRegistration: res.isReRegistration === true };
+}
+// ── Heartbeat ────────────────────────────────────────────────
+/**
+ * Keep the virtual screen "online" so GIVT screen-liveness (≤90s) lets the
+ * agent_direct completion bill. Uses the generic OpenRTB heartbeat — the earner
+ * heartbeat (/v2/earner/heartbeat/:id) 404s for virtual screens because the
+ * heartbeatMonitor only tracks physical/registered screens, whereas
+ * /openrtb/v1/heartbeat records liveness for ANY screenId. Public endpoint;
+ * best-effort (never throws), so a transient blip doesn't kill the loop.
+ */
+export async function sendVirtualScreenHeartbeat(baseUrl, screenId, deviceId = null) {
+    try {
+        const res = await fetch(new URL('/openrtb/v1/heartbeat', baseUrl).toString(), {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ screenId, deviceId: deviceId ?? undefined }),
+            signal: AbortSignal.timeout(5000),
+        });
+        return res.ok;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * GET /v2/earner/alot-advertisement-list/:screen_id and extract the web VAST tag.
+ *
+ * Response envelope: { status, code, message, data }. The programmatic block lives
+ * at `data.header_bidding_settings` with `vast_tag_url` (the winning tag) and
+ * `vast_waterfall.sources[].vast_url` (fallbacks). Returns nulls when no fill.
+ */
+export async function fetchVirtualScreenAds(baseUrl, screenId) {
+    const res = await fetch(new URL(`/v2/earner/alot-advertisement-list/${encodeURIComponent(screenId)}`, baseUrl).toString(), { headers: { Accept: 'application/json' }, signal: AbortSignal.timeout(10_000) });
+    if (!res.ok) {
+        throw new Error(`Ad fetch returned ${res.status}`);
+    }
+    const json = (await res.json());
+    const hbs = (json.data?.header_bidding_settings ?? null);
+    const vastTagUrl = hbs && typeof hbs.vast_tag_url === 'string' ? hbs.vast_tag_url : null;
+    const variantName = hbs && typeof hbs.variant_name === 'string' ? hbs.variant_name : null;
+    const sources = [];
+    const waterfall = hbs?.vast_waterfall;
+    if (waterfall && Array.isArray(waterfall.sources)) {
+        for (const s of waterfall.sources) {
+            if (s && typeof s.vast_url === 'string')
+                sources.push(s.vast_url);
+        }
+    }
+    return { vastTagUrl, variantName, sources };
+}
+/**
+ * GET /v2/earner/alot-advertisement-list/:screen_id and extract the TEXT creative
+ * from the first overlay advertisement. This is the no-browser, in-place surface:
+ * the agent-ads house/paid ad always carries name + campaign_link, so a sponsor
+ * LINE can render right in the agent's dead-time with zero video player.
+ *
+ * Returns null on no-fill (no overlay ad, or no usable headline). Tight default
+ * timeout — the Claude Code hook must stay fast and never block the prompt.
+ */
+export async function fetchVirtualScreenTextAd(baseUrl, screenId, timeoutMs = 2500) {
+    const res = await fetch(new URL(`/v2/earner/alot-advertisement-list/${encodeURIComponent(screenId)}`, baseUrl).toString(), { headers: { Accept: 'application/json' }, signal: AbortSignal.timeout(timeoutMs) });
+    if (!res.ok)
+        throw new Error(`Ad fetch returned ${res.status}`);
+    const json = (await res.json());
+    const overlays = json.data?.overlay_advertisements;
+    if (!Array.isArray(overlays) || overlays.length === 0)
+        return null;
+    const content = overlays[0]?.content;
+    if (!content || typeof content !== 'object')
+        return null;
+    const str = (v) => (typeof v === 'string' && v.trim() ? v.trim() : null);
+    const hbs = (json.data?.header_bidding_settings ?? null);
+    const name = str(content.name);
+    // No usable headline ⇒ nothing to render as a sponsor line.
+    if (!name)
+        return null;
+    return {
+        adId: str(content.id),
+        name,
+        description: str(content.description),
+        campaignLink: str(content.campaign_link),
+        variantName: hbs && typeof hbs.variant_name === 'string' ? hbs.variant_name : null,
+    };
+}
+/**
+ * GET the manifest declaring `?surface_capabilities=…` and return the chosen creative
+ * for whatever the host terminal can render. Forward-compatible: an old server ignores
+ * the param and returns its video/image creative; the new server's `selectCreativeFormat`
+ * honors it and may return text. Returns null on no-fill.
+ */
+export async function fetchVirtualScreenCreative(baseUrl, screenId, surfaceCapabilities, deviceId = null, timeoutMs = 4000) {
+    const url = new URL(`/v2/earner/alot-advertisement-list/${encodeURIComponent(screenId)}`, baseUrl);
+    if (surfaceCapabilities)
+        url.searchParams.set('surface_capabilities', surfaceCapabilities);
+    const res = await fetch(url.toString(), { headers: { Accept: 'application/json' }, signal: AbortSignal.timeout(timeoutMs) });
+    if (!res.ok)
+        throw new Error(`Ad fetch returned ${res.status}`);
+    const json = (await res.json());
+    const str = (v) => (typeof v === 'string' && v.trim() ? v.trim() : null);
+    const num = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : null);
+    const hbs = (json.data?.header_bidding_settings ?? null);
+    // Leg A: a playable programmatic VAST tag → the hosted IMA player URL. Built exactly
+    // like the screen app / ads-sdk ProgrammaticPlayer hand the tag to the IMA SDK; the
+    // wrap's signed pixels bill via `vast_event` when the player completes the ad.
+    const vastTagUrl = str(hbs?.vast_tag_url);
+    const variantName = str(hbs?.variant_name);
+    const imaPlayerUrl = vastTagUrl && isPlayableTagUrl(vastTagUrl)
+        ? buildImaPlayerUrl(baseUrl, screenId, vastTagUrl, deviceId, variantName)
+        : null;
+    const overlays = json.data?.overlay_advertisements;
+    const content = Array.isArray(overlays) && overlays.length > 0
+        ? overlays[0]?.content
+        : null;
+    // Leg-A-only fill: a programmatic tag with no direct/house overlay creative. Serve it
+    // anyway — the IMA player renders the VAST; there's no terminal media to show.
+    if (!content || typeof content !== 'object') {
+        if (!imaPlayerUrl)
+            return null;
+        return {
+            mediaType: 'video',
+            adId: null,
+            name: null,
+            description: null,
+            campaignLink: null,
+            variantName,
+            mediaUrl: null,
+            durationSeconds: null,
+            vastTagUrl,
+            imaPlayerUrl,
+            completeUrl: null,
+        };
+    }
+    const video = str(content.video);
+    const images = Array.isArray(content.image) ? content.image.map((x) => str(x)).filter(Boolean) : [];
+    const name = str(content.name);
+    // Trust the server's chosen mediaType; otherwise infer (video → image → text).
+    let mediaType = str(content.mediaType);
+    if (mediaType !== 'text' && mediaType !== 'image' && mediaType !== 'video') {
+        mediaType = video ? 'video' : images.length > 0 ? 'image' : 'text';
+    }
+    const mediaUrl = mediaType === 'video' ? video : mediaType === 'image' ? images[0] ?? null : null;
+    // Leg B needs renderable terminal media; a Leg-A (imaPlayerUrl) fill does not, so a
+    // missing direct creative is only a no-fill when there's also no programmatic tag.
+    if (!imaPlayerUrl) {
+        if (mediaType !== 'text' && !mediaUrl)
+            return null;
+        if (mediaType === 'text' && !name)
+            return null;
+    }
+    return {
+        mediaType,
+        adId: str(content.id),
+        name,
+        description: str(content.description),
+        campaignLink: str(content.campaign_link),
+        variantName,
+        mediaUrl,
+        durationSeconds: num(content.duration_seconds),
+        vastTagUrl,
+        imaPlayerUrl,
+        completeUrl: str(content.complete_url),
+    };
+}
+/**
+ * Fire the SERVER-SIGNED agent_direct completion beacon on play completion. The
+ * URL (with its `&sig=`) was minted by the serve path, so this passes
+ * VAST_ATTRIBUTION_REQUIRE_SIG — the wrapper never builds or signs the complete
+ * itself. Best-effort, fire-and-forget: never throws, returns true on a 2xx.
+ */
+export async function reportVirtualScreenCompletion(baseUrl, completeUrl) {
+    if (!completeUrl)
+        return false;
+    try {
+        const res = await fetch(new URL(completeUrl, baseUrl).toString(), {
+            method: 'POST',
+            signal: AbortSignal.timeout(5000),
+        });
+        return res.ok;
+    }
+    catch {
+        return false;
+    }
+}
+// ── Billable player URL ──────────────────────────────────────
+/**
+ * Build the URL-loadable, billable IMA player link. Opening this in a browser
+ * loads the hosted ima-player.js which fires the VAST impression/quartile/complete
+ * pixels (that is the money path — the TTY can't render video).
+ *
+ * The server-side `isAllowedTagUrl` SSRF allowlist gates the `tag` param to known
+ * ad-server hosts (GAM/doubleclick/adipolo/adtelligent/...). A non-allowlisted tag
+ * yields a 400 page, so we surface a clear hint when the tag won't be playable.
+ */
+export function buildImaPlayerUrl(baseUrl, screenId, vastTagUrl, deviceId, variantName) {
+    const url = new URL(`/openrtb/v1/ima-player/${encodeURIComponent(screenId)}`, baseUrl);
+    url.searchParams.set('tag', vastTagUrl);
+    if (deviceId)
+        url.searchParams.set('did', deviceId);
+    if (variantName)
+        url.searchParams.set('var', variantName);
+    return url.toString();
+}
+/** Hosts the server-side ima-player SSRF allowlist accepts for the `tag` param. */
+const ALLOWED_TAG_HOSTS = new Set([
+    'ad.vidverto.io',
+    'pubads.adipolo.co',
+    'pubads.g.doubleclick.net',
+    'video.incrementxserv.com',
+    'pagead2.googlesyndication.com',
+    'securepubads.g.doubleclick.net',
+    'googleads.g.doubleclick.net',
+    'www.googletagservices.com',
+    'ad.doubleclick.net',
+    'a.adtelligent.com',
+]);
+const ALLOWED_TAG_HOST_SUFFIXES = ['.adtelligent.com'];
+/**
+ * First-party vast-wrap proxy — the canonical BILLABLE tag (mirrors the server's
+ * `isFirstPartyVastProxyUrl` in routes/openrtb/ima-player.js). Our own /vast-wrap, /vast
+ * and /src forwarders inject the signed vast_event pixels, so the hosted player renders
+ * them; host- + path-restricted so it is not a blanket allow of our origin.
+ */
+const FIRST_PARTY_VAST_PROXY_PATH = /^\/openrtb\/v\d+\/(?:vast-wrap|vast|src)\//;
+function isFirstPartyVastProxyUrl(parsed) {
+    const host = parsed.hostname.toLowerCase();
+    const firstParty = host === 'trillboards.com' || host.endsWith('.trillboards.com');
+    return firstParty && FIRST_PARTY_VAST_PROXY_PATH.test(parsed.pathname);
+}
+/** Mirror of the server's allowlist so we can warn before printing an unplayable link. */
+export function isPlayableTagUrl(vastTagUrl) {
+    try {
+        const parsed = new URL(vastTagUrl);
+        if (parsed.protocol !== 'https:' && parsed.protocol !== 'http:')
+            return false;
+        const host = parsed.hostname.toLowerCase();
+        if (ALLOWED_TAG_HOSTS.has(host) || ALLOWED_TAG_HOST_SUFFIXES.some((suffix) => host.endsWith(suffix))) {
+            return true;
+        }
+        return isFirstPartyVastProxyUrl(parsed);
+    }
+    catch {
+        return false;
+    }
+}
+// ── Event reporting ──────────────────────────────────────────
+/**
+ * Report a text-ad / programmatic lifecycle event for the virtual screen via the
+ * public OpenRTB event endpoint (the partner programmatic-event route 403s for a
+ * partner-less screen). Best-effort, fire-and-forget; never throws.
+ *
+ * `adid` is required by the endpoint; for synthetic lifecycle events (request,
+ * no_fill) we pass a deterministic synthetic id.
+ */
+export async function reportTextAdEvent(baseUrl, params, timeoutMs = 5000) {
+    try {
+        const url = new URL('/openrtb/v1/event', baseUrl);
+        url.searchParams.set('adid', params.adid);
+        url.searchParams.set('event', params.event);
+        url.searchParams.set('screenId', params.screenId);
+        if (params.deviceId)
+            url.searchParams.set('deviceId', params.deviceId);
+        if (params.variantName)
+            url.searchParams.set('variant_name', params.variantName);
+        const res = await fetch(url.toString(), { method: 'POST', signal: AbortSignal.timeout(timeoutMs) });
+        return res.ok;
+    }
+    catch {
+        return false;
+    }
+}
+/** Generate a synthetic per-impression id for text-ad telemetry. */
+export function newImpressionId() {
+    return 'agentcli_' + crypto.randomBytes(8).toString('hex');
+}

package/dist/agent-hook.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Pure decision logic for the Claude Code dead-time hook (`ads hook`).
+ *
+ * The hook fires on every prompt submit (the moment the agent starts thinking).
+ * We render an in-place TEXT sponsor line — no browser, no video player — but only
+ * (a) when this install is a registered virtual screen, (b) at most once per
+ * interval (frequency cap), and (c) when there is a fillable text creative.
+ *
+ * Everything here is injectable + side-effect-free so it is fully unit-tested; the
+ * command wrapper supplies real config/network/clock. runAgentHook NEVER throws —
+ * any failure resolves to {} so the developer's prompt always proceeds.
+ */
+import type { VirtualScreenTextAd } from './ads-client.js';
+/** Default minimum gap between in-place sponsor lines (3 min). */
+export declare const AGENT_AD_MIN_INTERVAL_MS = 180000;
+/**
+ * Effective interval. A developer may tune their own cadence with
+ * TRILLBOARDS_AGENT_AD_INTERVAL_SECONDS (floored at 10s to prevent spam); otherwise
+ * the sane default. This is the dev's own machine preference, not a server flag.
+ */
+export declare function agentAdIntervalMs(): number;
+export declare function shouldShowAd(lastShownAt: number | undefined, now: number, intervalMs: number): boolean;
+/**
+ * Build the one-line sponsor message rendered to the developer (via the hook's
+ * `systemMessage`). Plain text — Claude Code styles it; the bare URL stays
+ * click-/copy-able in the terminal. Returns null when there is no usable headline.
+ */
+export declare function buildSponsorMessage(ad: VirtualScreenTextAd): string | null;
+export interface AgentHookDeps {
+    now: number;
+    screenId: string | null;
+    deviceId: string | null;
+    baseUrl: string;
+    lastShownAt: number | undefined;
+    intervalMs: number;
+    fetchTextAd: (baseUrl: string, screenId: string) => Promise<VirtualScreenTextAd | null>;
+    markShown: (now: number) => void;
+}
+/** Non-billable 'request' telemetry the COMMAND fires AFTER writing the render. */
+export interface AgentHookReport {
+    screenId: string;
+    deviceId: string | null;
+    event: string;
+    adid: string;
+    variantName: string | null;
+}
+export interface AgentHookResult {
+    /** Shown to the developer by Claude Code (never injected into the model context). */
+    systemMessage?: string;
+    /** Telemetry to fire after rendering; absent when nothing is shown or no creative id. */
+    report?: AgentHookReport;
+}
+/**
+ * Decide what to show. Returns {systemMessage, report?} ONLY when an ad is actually
+ * shown. Guards: registered? → interval elapsed? → filled? → renderable? Marks
+ * "shown" only on a real render (a no-fill retries next prompt).
+ *
+ * Telemetry is intentionally NOT fired here: the command writes the render to stdout
+ * FIRST and reports afterward, so a slow event endpoint can never hold the sponsor
+ * line past Claude Code's hook timeout. The 'request' event keys on the served
+ * creative id (an ObjectId the event endpoint accepts) — synthetic agentcli_ ids
+ * would be rejected as invalid_adid_format.
+ */
+export declare function runAgentHook(deps: AgentHookDeps): Promise<AgentHookResult>;

package/dist/agent-hook.js

@@ -0,0 +1,96 @@
+/**
+ * Pure decision logic for the Claude Code dead-time hook (`ads hook`).
+ *
+ * The hook fires on every prompt submit (the moment the agent starts thinking).
+ * We render an in-place TEXT sponsor line — no browser, no video player — but only
+ * (a) when this install is a registered virtual screen, (b) at most once per
+ * interval (frequency cap), and (c) when there is a fillable text creative.
+ *
+ * Everything here is injectable + side-effect-free so it is fully unit-tested; the
+ * command wrapper supplies real config/network/clock. runAgentHook NEVER throws —
+ * any failure resolves to {} so the developer's prompt always proceeds.
+ */
+/** Default minimum gap between in-place sponsor lines (3 min). */
+export const AGENT_AD_MIN_INTERVAL_MS = 180_000;
+/** Longest sponsor line we render before truncating (keeps it to one tasteful line). */
+const MAX_SPONSOR_LINE = 160;
+/**
+ * Effective interval. A developer may tune their own cadence with
+ * TRILLBOARDS_AGENT_AD_INTERVAL_SECONDS (floored at 10s to prevent spam); otherwise
+ * the sane default. This is the dev's own machine preference, not a server flag.
+ */
+export function agentAdIntervalMs() {
+    const raw = process.env.TRILLBOARDS_AGENT_AD_INTERVAL_SECONDS;
+    const n = raw ? Number.parseInt(raw, 10) : Number.NaN;
+    if (Number.isFinite(n) && n >= 10)
+        return n * 1000;
+    return AGENT_AD_MIN_INTERVAL_MS;
+}
+export function shouldShowAd(lastShownAt, now, intervalMs) {
+    if (!lastShownAt || !Number.isFinite(lastShownAt))
+        return true;
+    return now - lastShownAt >= intervalMs;
+}
+/**
+ * Build the one-line sponsor message rendered to the developer (via the hook's
+ * `systemMessage`). Plain text — Claude Code styles it; the bare URL stays
+ * click-/copy-able in the terminal. Returns null when there is no usable headline.
+ */
+export function buildSponsorMessage(ad) {
+    if (!ad.name)
+        return null;
+    let line = `◆ Sponsored · ${ad.name}`;
+    if (ad.description)
+        line += ` — ${ad.description}`;
+    if (line.length > MAX_SPONSOR_LINE)
+        line = line.slice(0, MAX_SPONSOR_LINE - 1).trimEnd() + '…';
+    if (ad.campaignLink)
+        line += `  ${ad.campaignLink}`;
+    return line;
+}
+/**
+ * Decide what to show. Returns {systemMessage, report?} ONLY when an ad is actually
+ * shown. Guards: registered? → interval elapsed? → filled? → renderable? Marks
+ * "shown" only on a real render (a no-fill retries next prompt).
+ *
+ * Telemetry is intentionally NOT fired here: the command writes the render to stdout
+ * FIRST and reports afterward, so a slow event endpoint can never hold the sponsor
+ * line past Claude Code's hook timeout. The 'request' event keys on the served
+ * creative id (an ObjectId the event endpoint accepts) — synthetic agentcli_ ids
+ * would be rejected as invalid_adid_format.
+ */
+export async function runAgentHook(deps) {
+    try {
+        if (!deps.screenId)
+            return {};
+        if (!shouldShowAd(deps.lastShownAt, deps.now, deps.intervalMs))
+            return {};
+        let ad = null;
+        try {
+            ad = await deps.fetchTextAd(deps.baseUrl, deps.screenId);
+        }
+        catch {
+            return {}; // fail open — never block the prompt on a fetch error
+        }
+        if (!ad)
+            return {};
+        const message = buildSponsorMessage(ad);
+        if (!message)
+            return {};
+        deps.markShown(deps.now);
+        const result = { systemMessage: message };
+        if (ad.adId) {
+            result.report = {
+                screenId: deps.screenId,
+                deviceId: deps.deviceId,
+                event: 'request',
+                adid: ad.adId,
+                variantName: ad.variantName,
+            };
+        }
+        return result;
+    }
+    catch {
+        return {};
+    }
+}

package/dist/capability.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Terminal surface-capability detection for the `trillboards code` wrapper.
+ *
+ * The render surface available during the agent's dead-time depends on the host
+ * terminal. We map the environment to four capabilities and hand them to the
+ * server as `?surface_capabilities=…` so it returns the richest creative the
+ * surface can actually show (the server's `selectCreativeFormat`).
+ *
+ *   text    — every TTY (an OSC-8 sponsor line)
+ *   image   — inline graphics (Kitty / iTerm2 / Sixel; incl. VS Code's terminal for STATIC images)
+ *   video   — real in-terminal video via `mpv --vo=kitty` (Kitty/Ghostty/iTerm2/WezTerm) — NOT VS Code/Cursor
+ *   webview — we can open an external browser/PiP for an IMA/AdX video (the Leg-A fallback)
+ *
+ * Pure + env-injectable so it is fully unit-tested.
+ */
+export interface SurfaceCapabilities {
+    text: boolean;
+    image: boolean;
+    /** Real in-terminal video (mpv --vo=kitty quality). VS Code/Cursor terminals = false. */
+    video: boolean;
+    /** Can open an external browser/PiP for an IMA/AdX video (the Leg-A fallback). */
+    webview: boolean;
+}
+/**
+ * Detect what the host terminal can render, from the environment alone (no
+ * round-trip probe — that lives in the wrapper which can do the Kitty `a=q` query
+ * for a runtime confirm). `env` is injected so tests cover the matrix.
+ */
+export declare function detectSurfaceCapabilities(env?: NodeJS.ProcessEnv): SurfaceCapabilities;
+/** Serialize for the `?surface_capabilities=` query param the server's selector reads. */
+export declare function capabilitiesToParam(caps: SurfaceCapabilities): string;