@trillboards/cli 0.1.0 → 0.1.1

package/dist/commands/generated/generated-federated-performance-upload.js

@@ -0,0 +1,32 @@
+// AUTO-GENERATED from OpenAPI spec (federated-api) -- do not edit manually
+// Regenerate with: npm run generate
+import { Flags } from '@oclif/core';
+import { BaseCommand } from '../../base-command.js';
+import { apiRequest } from '../../http.js';
+import { formatOutput } from '../../output.js';
+export default class Federatedperformanceupload extends BaseCommand {
+    static description = "Report on-device model performance metrics.";
+    static examples = [`$ trillboards generated federated-performance-upload`];
+    static args = {};
+    static flags = {
+        ...BaseCommand.baseFlags,
+        data: Flags.string({ description: 'JSON request body' }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(Federatedperformanceupload);
+        this.setParsedFlags(flags);
+        const apiKey = this.getApiKey();
+        if (!apiKey)
+            this.error('Not logged in. Run: trillboards login');
+        let urlPath = '/v1/federated/performance';
+        const params = {};
+        const body = flags.data ? JSON.parse(flags.data) : undefined;
+        const result = await apiRequest('POST', urlPath, {
+            apiKey,
+            baseUrl: flags['base-url'] ?? 'https://api.trillboards.com',
+            params: Object.keys(params).length > 0 ? params : undefined,
+            body,
+        });
+        this.log(formatOutput(result, this.getFormat()));
+    }
+}

package/dist/commands/generated/generated-federated-taste-upload.d.ts

@@ -0,0 +1,13 @@
+import { BaseCommand } from '../../base-command.js';
+export default class Federatedtasteupload extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static args: {};
+    static flags: {
+        data: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'api-key': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'base-url': import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        format: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/generated/generated-federated-taste-upload.js

@@ -0,0 +1,32 @@
+// AUTO-GENERATED from OpenAPI spec (federated-api) -- do not edit manually
+// Regenerate with: npm run generate
+import { Flags } from '@oclif/core';
+import { BaseCommand } from '../../base-command.js';
+import { apiRequest } from '../../http.js';
+import { formatOutput } from '../../output.js';
+export default class Federatedtasteupload extends BaseCommand {
+    static description = "Upload a screen-taste embedding for content personalization aggregation.";
+    static examples = [`$ trillboards generated federated-taste-upload`];
+    static args = {};
+    static flags = {
+        ...BaseCommand.baseFlags,
+        data: Flags.string({ description: 'JSON request body' }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(Federatedtasteupload);
+        this.setParsedFlags(flags);
+        const apiKey = this.getApiKey();
+        if (!apiKey)
+            this.error('Not logged in. Run: trillboards login');
+        let urlPath = '/v1/federated/taste';
+        const params = {};
+        const body = flags.data ? JSON.parse(flags.data) : undefined;
+        const result = await apiRequest('POST', urlPath, {
+            apiKey,
+            baseUrl: flags['base-url'] ?? 'https://api.trillboards.com',
+            params: Object.keys(params).length > 0 ? params : undefined,
+            body,
+        });
+        this.log(formatOutput(result, this.getFormat()));
+    }
+}

package/dist/commands/generated/generated-post-device-heartbeat.d.ts

@@ -0,0 +1,15 @@
+import { BaseCommand } from '../../base-command.js';
+export default class Postdeviceheartbeat extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static args: {
+        deviceId: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static flags: {
+        data: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'api-key': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'base-url': import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        format: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/generated/generated-post-device-heartbeat.js

@@ -0,0 +1,35 @@
+// AUTO-GENERATED from OpenAPI spec (device-api) -- do not edit manually
+// Regenerate with: npm run generate
+import { Args, Flags } from '@oclif/core';
+import { BaseCommand } from '../../base-command.js';
+import { apiRequest } from '../../http.js';
+import { formatOutput } from '../../output.js';
+export default class Postdeviceheartbeat extends BaseCommand {
+    static description = "Submit a device heartbeat.";
+    static examples = [`$ trillboards generated post-device-heartbeat`];
+    static args = {
+        deviceId: Args.string({ description: 'Device fingerprint or external device ID.', required: true }),
+    };
+    static flags = {
+        ...BaseCommand.baseFlags,
+        data: Flags.string({ description: 'JSON request body' }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(Postdeviceheartbeat);
+        this.setParsedFlags(flags);
+        const apiKey = this.getApiKey();
+        if (!apiKey)
+            this.error('Not logged in. Run: trillboards login');
+        let urlPath = '/v1/partner/device/{deviceId}/heartbeat';
+        urlPath = urlPath.replace('{deviceId}', args['deviceId']);
+        const params = {};
+        const body = flags.data ? JSON.parse(flags.data) : undefined;
+        const result = await apiRequest('POST', urlPath, {
+            apiKey,
+            baseUrl: flags['base-url'] ?? 'https://api.trillboards.com',
+            params: Object.keys(params).length > 0 ? params : undefined,
+            body,
+        });
+        this.log(formatOutput(result, this.getFormat()));
+    }
+}

package/dist/commands/listen.js

@@ -175,7 +175,15 @@ export default class Listen extends BaseCommand {
                 headers: {
                     'Content-Type': 'application/json',
                     'X-Trillboards-Event': envelope.event,
-                    'X-Trillboards-Signature': signature,
+                    // `sha256=` prefix matches the server-side verifier's expected
+                    // format (webhooks.ts:verifySignatureHeader). Emitting the bare
+                    // hex made the CLI's delivered payloads fail signature validation
+                    // silently on the receiving side.
+                    'X-Trillboards-Signature': `sha256=${signature}`,
+                    // Explicit send timestamp so receivers can implement replay
+                    // protection without trusting Date parsing of the default
+                    // `Date` header (which varies by node_fetch impl).
+                    'X-Trillboards-Timestamp': String(started),
                 },
                 method: 'POST',
                 signal: controller.signal,

package/dist/commands/logs/tail.js

@@ -108,7 +108,7 @@ export default class LogsTail extends BaseCommand {
      * Parse a status filter string like "4xx,5xx,200" into lookup patterns.
      */
     static parseStatusPatterns(raw) {
-        return raw.split(',').map((s) => s.trim()).filter(Boolean).map((token) => {
+        const patterns = raw.split(',').map((s) => s.trim()).filter(Boolean).map((token) => {
             const m = /^(\d)xx$/i.exec(token);
             if (m)
                 return { rangeStart: Number(m[1]) * 100 };
@@ -117,6 +117,15 @@ export default class LogsTail extends BaseCommand {
                 return { exact: n };
             return {};
         }).filter((p) => p.exact !== undefined || p.rangeStart !== undefined);
+        // Refuse to proceed on a filter string that matches nothing — previous
+        // silent fallback to "no filter" let typos (e.g. `--status xyz`) stream
+        // every event to the user and looked like a successful filter was
+        // applied. Fail loudly so the invocation can be fixed.
+        if (patterns.length === 0) {
+            throw new Error(`--status "${raw}" did not match any valid status pattern. ` +
+                `Use exact codes like 500 or ranges like 5xx, comma-separated.`);
+        }
+        return patterns;
     }
     static sleep(ms) {
         return new Promise((resolve) => {

package/dist/config.d.ts

@@ -3,6 +3,27 @@ export interface TrillboardsConfig {
     base_url?: string;
     default_format?: 'json' | 'table' | 'yaml';
     partner_name?: string;
+    user_token?: string;
+    user_refresh_token?: string;
+    /** Epoch milliseconds at which `user_token` expires (access token TTL is 1h). */
+    user_token_expires_at?: number;
+    user_email?: string;
+    /**
+     * Stable per-install machine id — a generated UUID persisted here on first
+     * `ads start`. Deliberately NOT derived from hostname so it survives renames
+     * and uniquely identifies this install for idempotent virtual-screen registration.
+     */
+    machine_id?: string;
+    /** Registered virtual-screen Mongo id (from /v2/earner/virtual-screen/register). */
+    screen_id?: string;
+    /** Registered virtual-screen device Mongo id (from the same register call). */
+    device_id?: string;
+    /**
+     * Epoch ms of the last in-place sponsor line shown by the Claude Code dead-time
+     * hook (`ads hook`). Frequency-caps the hook so it surfaces at most once per
+     * interval instead of on every prompt.
+     */
+    agent_hook_last_shown_at?: number;
 }
 export declare function readConfig(): TrillboardsConfig;
 export declare function writeConfig(config: TrillboardsConfig): void;

package/dist/config.js

@@ -1,18 +1,32 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
-const CONFIG_DIR = join(homedir(), '.trillboards');
-const CONFIG_FILE = join(CONFIG_DIR, 'config.json');
+/**
+ * Config directory. Overridable via TRILLBOARDS_CONFIG_DIR so tests never touch
+ * the real ~/.trillboards/config.json (which holds live credentials).
+ */
+function configDir() {
+    const override = process.env.TRILLBOARDS_CONFIG_DIR;
+    if (override && override.trim())
+        return override;
+    return join(homedir(), '.trillboards');
+}
+function configFile() {
+    return join(configDir(), 'config.json');
+}
 function ensureConfigDir() {
-    if (!existsSync(CONFIG_DIR)) {
-        mkdirSync(CONFIG_DIR, { recursive: true });
+    const dir = configDir();
+    if (!existsSync(dir)) {
+        // 0o700 — owner-only, matching the sensitivity of stored tokens/keys.
+        mkdirSync(dir, { mode: 0o700, recursive: true });
     }
 }
 export function readConfig() {
     try {
-        if (!existsSync(CONFIG_FILE))
+        const file = configFile();
+        if (!existsSync(file))
             return {};
-        const raw = readFileSync(CONFIG_FILE, 'utf-8');
+        const raw = readFileSync(file, 'utf-8');
         return JSON.parse(raw);
     }
     catch {
@@ -21,12 +35,23 @@ export function readConfig() {
 }
 export function writeConfig(config) {
     ensureConfigDir();
-    writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2) + '\n', 'utf-8');
+    const file = configFile();
+    // 0o600 — owner read/write only. Tokens and the partner key live here. The
+    // writeFileSync `mode` only applies when CREATING the file, so chmod explicitly
+    // afterward to also tighten a PRE-EXISTING config (e.g. one written by the partner
+    // `login` command before this hardening). Codex P2 on PR #7282.
+    writeFileSync(file, JSON.stringify(config, null, 2) + '\n', { encoding: 'utf-8', mode: 0o600 });
+    try {
+        chmodSync(file, 0o600);
+    }
+    catch {
+        // Best-effort: platforms without POSIX permissions (e.g. Windows) ignore chmod.
+    }
 }
 export function updateConfig(updates) {
     const existing = readConfig();
     writeConfig({ ...existing, ...updates });
 }
 export function getConfigPath() {
-    return CONFIG_FILE;
+    return configFile();
 }

package/dist/dead-time.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Dead-time detection for the `trillboards code` PTY wrapper.
+ *
+ * The wrapper tees the wrapped agent's terminal output through this detector. The
+ * agent's "thinking" state is signalled by an actively-redrawing spinner line
+ * (braille frames + "esc to interrupt"); the moment the agent starts streaming its
+ * answer, real content flows. So:  spinner ⇒ enter dead-time,  content ⇒ exit.
+ *
+ * The classifiers are pure and the state machine takes an injected clock, so the
+ * whole thing is unit-tested. The exact spinner signature is broad (braille +
+ * common glyph sets + "esc to interrupt") and tunable against real agent output.
+ */
+/** True when a chunk is a spinner redraw (the agent is thinking, not emitting answer text). */
+export declare function isSpinnerChunk(chunk: string): boolean;
+/** True when a chunk carries substantial agent answer text (≈ streaming has begun). */
+export declare function isContentChunk(chunk: string, minChars?: number): boolean;
+export interface DeadTimeOptions {
+    now?: () => number;
+    /** A spinner must persist this long before we treat it as real dead-time (debounce flicker). */
+    spinnerStartMs?: number;
+    /** No spinner activity for this long ⇒ thinking ended (safety exit). */
+    spinnerStopMs?: number;
+}
+export interface DeadTimeCallbacks {
+    onEnter: () => void;
+    onExit: () => void;
+}
+/**
+ * Streaming state machine. Feed it the agent's output chunks (`feed`) and the
+ * user's keystrokes (`onUserInput`), and call `tick()` periodically; it invokes
+ * onEnter/onExit exactly on the dead-time boundaries. Never throws.
+ */
+export declare class DeadTimeDetector {
+    private readonly now;
+    private readonly spinnerStartMs;
+    private readonly spinnerStopMs;
+    private readonly cb;
+    private inDeadTime;
+    private firstSpinnerAt;
+    private lastSpinnerAt;
+    constructor(cb: DeadTimeCallbacks, opts?: DeadTimeOptions);
+    get inDeadTimeNow(): boolean;
+    /** Process a chunk of the agent's terminal output. */
+    feed(chunk: string): void;
+    /** The developer typed — treat as the end of dead-time (they're back in control). */
+    onUserInput(): void;
+    /** Call periodically; exits dead-time if the spinner has been quiet (agent finished). */
+    tick(): void;
+    private enter;
+    private exit;
+}

package/dist/dead-time.js

@@ -0,0 +1,119 @@
+/**
+ * Dead-time detection for the `trillboards code` PTY wrapper.
+ *
+ * The wrapper tees the wrapped agent's terminal output through this detector. The
+ * agent's "thinking" state is signalled by an actively-redrawing spinner line
+ * (braille frames + "esc to interrupt"); the moment the agent starts streaming its
+ * answer, real content flows. So:  spinner ⇒ enter dead-time,  content ⇒ exit.
+ *
+ * The classifiers are pure and the state machine takes an injected clock, so the
+ * whole thing is unit-tested. The exact spinner signature is broad (braille +
+ * common glyph sets + "esc to interrupt") and tunable against real agent output.
+ */
+// Braille spinner range (Claude Code / many TUIs animate these) + circle spinners.
+// Deliberately NO ASCII punctuation (| / \ -): those appear constantly in normal
+// agent output (paths, flags, URLs, markdown bullets, code) and would misclassify
+// real content as a spinner redraw. The "esc to interrupt" hint is the strong signal.
+const SPINNER_GLYPHS = /[⠀-⣿◐-◓◰-◷]/;
+const INTERRUPT_HINT = /esc to (?:interrupt|cancel)/i;
+// Strip ANSI/OSC/cursor control so we can measure "real" printable content.
+const ANSI = /\[[0-9;?]*[ -/]*[@-~]/g;
+const OSC = /\][^]*?(?:|\\)/g;
+const CR_REDRAW = /[\r]/g;
+/** True when a chunk is a spinner redraw (the agent is thinking, not emitting answer text). */
+export function isSpinnerChunk(chunk) {
+    if (INTERRUPT_HINT.test(chunk))
+        return true;
+    // A spinner redraw is short and carries a spinner glyph (often after a CR).
+    if (chunk.length <= 400 && SPINNER_GLYPHS.test(chunk))
+        return true;
+    return false;
+}
+/** True when a chunk carries substantial agent answer text (≈ streaming has begun). */
+export function isContentChunk(chunk, minChars = 12) {
+    if (isSpinnerChunk(chunk))
+        return false; // a spinner redraw is never "content"
+    const stripped = chunk.replace(ANSI, '').replace(OSC, '').replace(CR_REDRAW, '').trim();
+    // Count letters/digits — prose, not pure punctuation/box-drawing.
+    const wordChars = (stripped.match(/[\p{L}\p{N}]/gu) ?? []).length;
+    return wordChars >= minChars;
+}
+/**
+ * Streaming state machine. Feed it the agent's output chunks (`feed`) and the
+ * user's keystrokes (`onUserInput`), and call `tick()` periodically; it invokes
+ * onEnter/onExit exactly on the dead-time boundaries. Never throws.
+ */
+export class DeadTimeDetector {
+    now;
+    spinnerStartMs;
+    spinnerStopMs;
+    cb;
+    inDeadTime = false;
+    firstSpinnerAt = null;
+    lastSpinnerAt = 0;
+    constructor(cb, opts = {}) {
+        this.cb = cb;
+        this.now = opts.now ?? (() => Date.now());
+        this.spinnerStartMs = opts.spinnerStartMs ?? 250;
+        this.spinnerStopMs = opts.spinnerStopMs ?? 1200;
+    }
+    get inDeadTimeNow() {
+        return this.inDeadTime;
+    }
+    /** Process a chunk of the agent's terminal output. */
+    feed(chunk) {
+        try {
+            if (isSpinnerChunk(chunk)) {
+                const t = this.now();
+                if (this.firstSpinnerAt === null)
+                    this.firstSpinnerAt = t;
+                this.lastSpinnerAt = t;
+                // Enter only once the spinner has persisted past the debounce window.
+                if (!this.inDeadTime && t - this.firstSpinnerAt >= this.spinnerStartMs) {
+                    this.enter();
+                }
+                return;
+            }
+            if (isContentChunk(chunk)) {
+                // Real answer text began → thinking is over.
+                this.firstSpinnerAt = null;
+                if (this.inDeadTime)
+                    this.exit();
+            }
+        }
+        catch {
+            // never let detection break the wrapped agent
+        }
+    }
+    /** The developer typed — treat as the end of dead-time (they're back in control). */
+    onUserInput() {
+        this.firstSpinnerAt = null;
+        if (this.inDeadTime)
+            this.exit();
+    }
+    /** Call periodically; exits dead-time if the spinner has been quiet (agent finished). */
+    tick() {
+        if (this.inDeadTime && this.now() - this.lastSpinnerAt >= this.spinnerStopMs) {
+            this.exit();
+        }
+    }
+    enter() {
+        this.inDeadTime = true;
+        try {
+            this.cb.onEnter();
+        }
+        catch {
+            /* ignore */
+        }
+    }
+    exit() {
+        this.inDeadTime = false;
+        this.firstSpinnerAt = null;
+        try {
+            this.cb.onExit();
+        }
+        catch {
+            /* ignore */
+        }
+    }
+}

package/dist/format-helpers.d.ts

@@ -11,6 +11,12 @@ export declare const ansi: {
     readonly yellow: "\u001B[33m";
 };
 export declare function colorize(text: string, color: keyof typeof ansi): string;
+/**
+ * Wrap text in an OSC-8 terminal hyperlink. Supporting terminals render `label` as a
+ * clickable link to `url`; others just show the label (so always print the raw URL too).
+ * OSC-8: ESC ] 8 ; ; <url> BEL <label> ESC ] 8 ; ; BEL
+ */
+export declare function osc8(url: string, label: string): string;
 /**
  * Format a number as USD currency: $1,234.56
  */

package/dist/format-helpers.js

@@ -16,6 +16,16 @@ export function colorize(text, color) {
         return text;
     return `${ansi[color]}${text}${ansi.reset}`;
 }
+/**
+ * Wrap text in an OSC-8 terminal hyperlink. Supporting terminals render `label` as a
+ * clickable link to `url`; others just show the label (so always print the raw URL too).
+ * OSC-8: ESC ] 8 ; ; <url> BEL <label> ESC ] 8 ; ; BEL
+ */
+export function osc8(url, label) {
+    const ESC = String.fromCharCode(27); // \x1b
+    const BEL = String.fromCharCode(7); //  \x07 terminates the OSC sequence
+    return `${ESC}]8;;${url}${BEL}${label}${ESC}]8;;${BEL}`;
+}
 /**
  * Format a number as USD currency: $1,234.56
  */

package/dist/http.d.ts

@@ -5,7 +5,14 @@ export declare class TrillboardsApiError extends Error {
     static fromResponse(body: Record<string, unknown>, statusCode: number): TrillboardsApiError;
 }
 export interface ApiRequestOptions {
-    apiKey: string;
+    /** Partner API key (trb_partner_*). Sent as `Authorization: Bearer <apiKey>`. */
+    apiKey?: string;
+    /**
+     * User JWT (the agent-ads developer identity). When set, it takes precedence
+     * over `apiKey` for the Authorization header. Distinct from `apiKey` because
+     * user-JWT routes (e.g. /v2/earner/virtual-screen/register) only accept a JWT.
+     */
+    token?: string;
     baseUrl: string;
     body?: unknown;
     params?: Record<string, string>;

package/dist/http.js

@@ -24,11 +24,16 @@ export async function apiRequest(method, path, options) {
         }
     }
     const headers = {
-        'Authorization': `Bearer ${options.apiKey}`,
         'Content-Type': 'application/json',
         'User-Agent': `trillboards-cli/${VERSION}`,
         'X-Trillboards-Client-Type': 'agent',
     };
+    // Prefer the user JWT when present; fall back to the partner API key. Only one
+    // Authorization scheme is sent. Public routes pass neither.
+    const bearer = options.token || options.apiKey;
+    if (bearer) {
+        headers.Authorization = `Bearer ${bearer}`;
+    }
     const response = await fetch(url.toString(), {
         body: options.body ? JSON.stringify(options.body) : undefined,
         headers,

package/dist/machine-id.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Resolve a STABLE per-install machine id.
+ *
+ * Deliberately a generated UUID persisted in config — NOT derived from hostname.
+ * Hostnames change (DHCP, renames, containers) and collide across machines; a
+ * persisted UUID uniquely and durably identifies this install, which is what the
+ * virtual-screen idempotency key (md5(userMongoId:machineId)) needs so the same
+ * install always maps to the same virtual screen.
+ *
+ * First call generates + persists; subsequent calls return the persisted value.
+ */
+export declare function getStableMachineId(): string;

package/dist/machine-id.js

@@ -0,0 +1,22 @@
+import crypto from 'node:crypto';
+import { readConfig, updateConfig } from './config.js';
+/**
+ * Resolve a STABLE per-install machine id.
+ *
+ * Deliberately a generated UUID persisted in config — NOT derived from hostname.
+ * Hostnames change (DHCP, renames, containers) and collide across machines; a
+ * persisted UUID uniquely and durably identifies this install, which is what the
+ * virtual-screen idempotency key (md5(userMongoId:machineId)) needs so the same
+ * install always maps to the same virtual screen.
+ *
+ * First call generates + persists; subsequent calls return the persisted value.
+ */
+export function getStableMachineId() {
+    const cfg = readConfig();
+    if (cfg.machine_id && cfg.machine_id.trim()) {
+        return cfg.machine_id;
+    }
+    const id = crypto.randomUUID();
+    updateConfig({ machine_id: id });
+    return id;
+}

package/dist/pty-wrapper.d.ts

@@ -0,0 +1,46 @@
+/**
+ * The `trillboards code` PTY wrapper core.
+ *
+ * Spawns the real coding agent under a pseudo-terminal we own, and passes bytes
+ * through verbatim in both directions — so the agent (Claude Code / Codex / …) runs
+ * byte-for-byte normally (alt-screen, raw mode, resize, paste all flow through). We
+ * only TEE the agent's output into the dead-time detector; when the agent starts
+ * "thinking", we play an ad on a side surface, and tear it down when it resumes.
+ *
+ * This is the I/O glue — the decision logic (dead-time, capability, render commands,
+ * fetch) all lives in unit-tested pure modules. Never lets ad logic break the agent.
+ */
+import type { VirtualScreenCreative } from './ads-client.js';
+import type { SurfaceCapabilities } from './capability.js';
+/** True iff the optional node-pty native module loaded — i.e. `code` can ad-wrap. */
+export declare function isPtyAvailable(): boolean;
+export interface WrapperDeps {
+    caps: SurfaceCapabilities;
+    capabilitiesParam: string;
+    /** Fetch the best creative for our surface (returns null on no-fill). */
+    fetchCreative: (capabilitiesParam: string) => Promise<VirtualScreenCreative | null>;
+    /** Report the impression (best-effort telemetry; the wrapper never blocks on it). */
+    reportImpression: (creative: VirtualScreenCreative) => Promise<unknown>;
+    /**
+     * Fire the server-signed completion beacon when an ad finishes playing
+     * (play-and-count; the billable agent_direct signal). Best-effort, non-blocking.
+     */
+    reportCompletion: (creative: VirtualScreenCreative) => Promise<unknown>;
+    /** Keep the virtual screen online for serving/billing. */
+    heartbeat: () => Promise<unknown>;
+    /** Minimum gap between ads (frequency cap). */
+    intervalMs: number;
+}
+/**
+ * Run the agent under a PTY and serve ads into its dead-time. Resolves with the
+ * agent's exit code. Restores the terminal + tears down all timers/renders on exit.
+ */
+export declare function runWrappedAgent(agent: string, agentArgs: string[], deps: WrapperDeps): Promise<number>;
+/**
+ * Run the agent verbatim with inherited stdio (NO ad-wrapping). The graceful fallback
+ * when node-pty is unavailable — the developer's coding agent works exactly as normal;
+ * they just don't earn from `code` here (they can run `trillboards ads enable`, the text
+ * hook, which needs no native deps and works in every terminal). Resolves with the
+ * agent's exit code.
+ */
+export declare function runAgentPassthrough(agent: string, agentArgs: string[]): Promise<number>;