@indigoai-us/hq-cli 5.345.178 → 5.345.180

package/dist/lib/hot-channels/run.d.ts

@@ -0,0 +1,137 @@
+/**
+ * On-demand hot-channel sync (US-004): `hq sources sync`.
+ *
+ * Joins the server's hot-channel catalog with the person's usable connections
+ * and the adapters this build registers, then runs the shared loop through
+ * `runHotChannelSync` with trigger `on-demand`. Each poll adapter runs once
+ * per usable connection, with its cursor keyed per connection. A channel whose
+ * token comes from the HQ vault (meetings) runs once with no connection.
+ *
+ * Network access is injected (`deps`), so this module holds no HTTP code and
+ * never sees an integration token: adapters call tools through a gateway
+ * handle bound to one connection. Writes land only under `sources/` (cursors,
+ * landed documents, the run ledger).
+ */
+import type { CatchUpWindow, HotTransport, SuggestionRule, TokenScope } from "./contract.js";
+import { type RunLedgerEntry, type RunTrigger, type SignalsGeneratedFn } from "./ledger.js";
+import type { HotChannelRegistry } from "./registry.js";
+/** One item of the catalog API's top-level `hotChannels` array (hq-pro US-002). */
+export interface HotChannelCatalogItem {
+    entryId?: string;
+    provider: string;
+    displayName?: string;
+    domain?: string;
+    flag?: string;
+    hotChannel: {
+        transport: HotTransport;
+        hotEventTypes: readonly string[];
+        catchUpWindow: CatchUpWindow;
+        tokenScope: TokenScope;
+        suggestionRule: SuggestionRule;
+    };
+}
+/** The fields of a usable connection the sync needs (a subset of `UsableApp`). */
+export interface HotChannelApp {
+    connectionId: string;
+    name: string;
+    provider: string;
+    status: string;
+    /**
+     * True when the signed-in person created this connection (server-computed
+     * `viewerAccess.isCreator`). Unknown counts as not theirs.
+     */
+    ownedByCaller?: boolean;
+}
+/** Token-scope providers served from the HQ vault: no external connection. */
+/**
+ * The bare, lowercased provider id used to match a connection against a
+ * catalog provider or an adapter's `companionProviders`. Factory installs store
+ * `factory:{slug}` (CLI installs `factory:cli:{slug}`); Slack stores `slack`.
+ */
+export declare function hotChannelProviderKey(provider: string): string;
+/** Usable meeting-recorder connections this person created, for a companion-fed adapter. */
+export declare function companionApps(apps: readonly HotChannelApp[], companionProviders: readonly string[]): HotChannelApp[];
+export declare const VAULT_TOKEN_PROVIDERS: ReadonlySet<string>;
+export declare const UNAVAILABLE_ADAPTER_MESSAGE = "adapter not available in this hq version";
+export type ReconnectReason = "signed-out" | "revoked";
+/**
+ * A gateway call failed because the HQ session is gone or the connection's
+ * token was revoked. The poll page that raised it is not landed, so the cursor
+ * stays where it was.
+ */
+export declare class HotChannelReconnectError extends Error {
+    readonly connectionId: string;
+    readonly provider: string;
+    readonly appName: string;
+    readonly reason: ReconnectReason;
+    readonly code = "HOT_CHANNEL_RECONNECT_REQUIRED";
+    constructor(connectionId: string, provider: string, appName: string, reason: ReconnectReason);
+}
+export declare class UnknownSyncAdapterError extends Error {
+    readonly adapter: string;
+    readonly valid: readonly string[];
+    readonly code = "HOT_CHANNEL_UNKNOWN_SYNC_ADAPTER";
+    constructor(adapter: string, valid: readonly string[]);
+}
+export interface OnDemandSyncDeps {
+    /** The catalog's `hotChannels`; null when the server does not publish them. */
+    fetchHotChannels(): Promise<HotChannelCatalogItem[] | null>;
+    /** Connections the person created or was granted and may use now. */
+    fetchUsableApps(): Promise<HotChannelApp[]>;
+    /** Call one tool on one connection through the HQ gateway. */
+    callTool(app: HotChannelApp, tool: string, args: Record<string, unknown>): Promise<unknown>;
+}
+export interface OnDemandSyncInput {
+    deps: OnDemandSyncDeps;
+    registry: HotChannelRegistry;
+    vaultRoot: string;
+    personUid: string;
+    personKey: string;
+    /** `--adapter`: a catalog provider or a registered adapter id. */
+    adapter?: string;
+    now?: () => Date;
+    runId?: string;
+    maxPagesPerAdapter?: number;
+    /** `scheduled` when the bot's hot-signal-sync job runs it; `on-demand` by default. */
+    trigger?: RunTrigger;
+    /** A scheduled run that fired late, after a missed window. */
+    catchUp?: boolean;
+    /** The signals pass over each adapter's landed sources (US-011); 0 when absent. */
+    signalsGenerated?: SignalsGeneratedFn;
+    /** Checked before each document write (sync-lock ownership); a throw stops the run. */
+    beforeWrite?: () => Promise<void>;
+}
+export type SyncOutcomeStatus = "ok" | "failed" | "unavailable" | "no-connection" | "gated";
+export interface SyncOutcome {
+    adapter: string;
+    provider: string;
+    connectionId: string | null;
+    appName: string | null;
+    status: SyncOutcomeStatus;
+    landed: number;
+    duplicates: number;
+    message: string | null;
+    /** Set when the person must sign in again or reconnect this connection. */
+    reconnect?: {
+        reason: ReconnectReason;
+        prompt: string;
+    };
+}
+export interface OnDemandSyncReport {
+    runId: string | null;
+    /** True when the HQ session was gone before anything ran; nothing was written. */
+    signInRequired: boolean;
+    /** True when another sync for this person and company was running; nothing ran. */
+    skipped?: boolean;
+    outcomes: SyncOutcome[];
+    entries: RunLedgerEntry[];
+    /** Lines for the person (no channels, sign-in needed). */
+    notices: string[];
+    exitCode: 0 | 1;
+}
+/** The line that tells the person how to get one connection syncing again. */
+export declare function reconnectPrompt(app: HotChannelApp, reason: ReconnectReason): string;
+/** Refuse any path that does not resolve inside `{vaultRoot}/sources/`. */
+export declare function assertInsideSources(vaultRoot: string, file: string): void;
+export declare function runOnDemandSync(input: OnDemandSyncInput): Promise<OnDemandSyncReport>;
+//# sourceMappingURL=run.d.ts.map

package/dist/lib/hot-channels/run.js

@@ -0,0 +1,324 @@
+/**
+ * On-demand hot-channel sync (US-004): `hq sources sync`.
+ *
+ * Joins the server's hot-channel catalog with the person's usable connections
+ * and the adapters this build registers, then runs the shared loop through
+ * `runHotChannelSync` with trigger `on-demand`. Each poll adapter runs once
+ * per usable connection, with its cursor keyed per connection. A channel whose
+ * token comes from the HQ vault (meetings) runs once with no connection.
+ *
+ * Network access is injected (`deps`), so this module holds no HTTP code and
+ * never sees an integration token: adapters call tools through a gateway
+ * handle bound to one connection. Writes land only under `sources/` (cursors,
+ * landed documents, the run ledger).
+ */
+import * as path from "node:path";
+import { isAuthError } from "../../utils/auth-error.js";
+import { bareProvider } from "../integrations/provider-slug.js";
+import { createVaultCursorStore } from "./cursors.js";
+import { cursorFilePath } from "./cursors.js";
+import { runHotChannelSync } from "./ledger.js";
+/** Token-scope providers served from the HQ vault: no external connection. */
+/**
+ * The bare, lowercased provider id used to match a connection against a
+ * catalog provider or an adapter's `companionProviders`. Factory installs store
+ * `factory:{slug}` (CLI installs `factory:cli:{slug}`); Slack stores `slack`.
+ */
+export function hotChannelProviderKey(provider) {
+    return provider.trim().toLowerCase().replace(/^factory:(cli:)?/, "");
+}
+/** Usable meeting-recorder connections this person created, for a companion-fed adapter. */
+export function companionApps(apps, companionProviders) {
+    const names = new Set(companionProviders.map(hotChannelProviderKey));
+    // Meetings are personal: only connections this person created, never a
+    // teammate's company-scope Fireflies or Granola.
+    return apps.filter((app) => names.has(hotChannelProviderKey(app.provider)) && app.status !== "needs-attention" && app.ownedByCaller === true);
+}
+export const VAULT_TOKEN_PROVIDERS = new Set(["hq-vault"]);
+export const UNAVAILABLE_ADAPTER_MESSAGE = "adapter not available in this hq version";
+/**
+ * A gateway call failed because the HQ session is gone or the connection's
+ * token was revoked. The poll page that raised it is not landed, so the cursor
+ * stays where it was.
+ */
+export class HotChannelReconnectError extends Error {
+    connectionId;
+    provider;
+    appName;
+    reason;
+    code = "HOT_CHANNEL_RECONNECT_REQUIRED";
+    constructor(connectionId, provider, appName, reason) {
+        super(reason === "signed-out"
+            ? `HQ session expired while syncing ${appName} (${connectionId})`
+            : `${appName} connection ${connectionId} needs to be reconnected`);
+        this.connectionId = connectionId;
+        this.provider = provider;
+        this.appName = appName;
+        this.reason = reason;
+        this.name = "HotChannelReconnectError";
+    }
+}
+export class UnknownSyncAdapterError extends Error {
+    adapter;
+    valid;
+    code = "HOT_CHANNEL_UNKNOWN_SYNC_ADAPTER";
+    constructor(adapter, valid) {
+        super(valid.length > 0
+            ? `Unknown adapter '${adapter}'. Valid adapters: ${valid.join(", ")}.`
+            : `Unknown adapter '${adapter}'. No hot channels are available.`);
+        this.adapter = adapter;
+        this.valid = valid;
+        this.name = "UnknownSyncAdapterError";
+    }
+}
+const SIGN_IN_PROMPT = "Your HQ session has expired or you're not signed in. Run `hq login`, then `hq sources sync` again.";
+const REVOKED_PATTERN = /revoked|reconnect|invalid_grant|token (has )?expired|OAUTH_REQUIRED/i;
+function statusOf(err) {
+    const status = err?.status;
+    return typeof status === "number" ? status : undefined;
+}
+function isSignedOut(err) {
+    return isAuthError(err) || statusOf(err) === 401;
+}
+function isRevoked(err) {
+    if (statusOf(err) === 403)
+        return true;
+    const code = err?.code;
+    if (typeof code === "string" && REVOKED_PATTERN.test(code))
+        return true;
+    return err instanceof Error && REVOKED_PATTERN.test(err.message);
+}
+/** The line that tells the person how to get one connection syncing again. */
+export function reconnectPrompt(app, reason) {
+    if (reason === "signed-out") {
+        return `Your HQ session expired while syncing ${app.name} (${app.connectionId}). Run \`hq login\`, then \`hq sources sync\` again.`;
+    }
+    return `Reconnect ${app.name} (${app.connectionId}): hq integrations connect ${bareProvider(app.provider)}`;
+}
+/**
+ * Gated adapters (US-013) whose flag is off for this company. hq-pro lists a
+ * gated channel in the catalog only while its flag is on, so a registered
+ * adapter with a `gate` that no catalog item resolves to is gated off. These
+ * are reported but never planned: no fetch, no cursor and no ledger line.
+ */
+function gatedOutcomes(registry, resolvedIds, wanted) {
+    const out = [];
+    for (const adapter of registry.list()) {
+        if (!adapter.gate || resolvedIds.has(adapter.id))
+            continue;
+        const provider = adapter.tokenScope.provider;
+        if (wanted !== undefined && adapter.id !== wanted && provider.toLowerCase() !== wanted)
+            continue;
+        out.push({
+            adapter: adapter.id,
+            provider: provider || adapter.id,
+            connectionId: null,
+            appName: null,
+            status: "gated",
+            landed: 0,
+            duplicates: 0,
+            message: `${adapter.id} is not enabled for this company (flag ${adapter.gate.flag} is off)`,
+        });
+    }
+    return out;
+}
+function resolveAdapter(registry, item) {
+    for (const key of [item.hotChannel.tokenScope.provider, item.provider]) {
+        try {
+            return { adapter: registry.resolve({ provider: key }), key };
+        }
+        catch {
+            // Not registered under this key; try the next one.
+        }
+    }
+    return null;
+}
+/**
+ * The gateway handle a poll adapter gets for one connection. Auth failures
+ * become `HotChannelReconnectError`, which the loop records on the run result
+ * before any cursor moves.
+ */
+function gatewayFor(app, deps, reconnects) {
+    return {
+        connectionId: app.connectionId,
+        provider: bareProvider(app.provider),
+        async call(tool, args) {
+            try {
+                return await deps.callTool(app, tool, args);
+            }
+            catch (err) {
+                const reason = isSignedOut(err) ? "signed-out" : isRevoked(err) ? "revoked" : null;
+                if (reason === null)
+                    throw err;
+                reconnects.set(app.connectionId, reason);
+                throw new HotChannelReconnectError(app.connectionId, bareProvider(app.provider), app.name, reason);
+            }
+        },
+    };
+}
+/** Refuse any path that does not resolve inside `{vaultRoot}/sources/`. */
+export function assertInsideSources(vaultRoot, file) {
+    const root = path.resolve(vaultRoot, "sources") + path.sep;
+    if (!path.resolve(file).startsWith(root)) {
+        throw new Error(`hq sources sync only writes under sources/ (refused ${file})`);
+    }
+}
+/** The vault cursor store, with every write checked against `sources/`. */
+function sourcesOnlyCursorStore(vaultRoot, now) {
+    const store = createVaultCursorStore(vaultRoot, now ? { now } : {});
+    return {
+        get: (personKey, key) => store.get(personKey, key),
+        async set(personKey, key, cursor, lastEventKey) {
+            assertInsideSources(vaultRoot, cursorFilePath(vaultRoot, personKey, key));
+            await store.set(personKey, key, cursor, lastEventKey);
+        },
+    };
+}
+export async function runOnDemandSync(input) {
+    const report = {
+        runId: null,
+        signInRequired: false,
+        outcomes: [],
+        entries: [],
+        notices: [],
+        exitCode: 0,
+    };
+    let items;
+    let apps;
+    try {
+        [items, apps] = await Promise.all([input.deps.fetchHotChannels(), input.deps.fetchUsableApps()]);
+    }
+    catch (err) {
+        if (!isSignedOut(err))
+            throw err;
+        report.signInRequired = true;
+        report.notices.push(SIGN_IN_PROMPT);
+        report.exitCode = 1;
+        return report;
+    }
+    const wanted = input.adapter?.toLowerCase();
+    if (!items || items.length === 0) {
+        const gated = gatedOutcomes(input.registry, new Set(), wanted);
+        if (wanted !== undefined && gated.length === 0)
+            throw new UnknownSyncAdapterError(input.adapter, []);
+        if (wanted === undefined)
+            report.notices.push("No hot channels are available for this company.");
+        report.outcomes.push(...gated);
+        return report;
+    }
+    const resolved = items.map((item) => ({ item, hit: resolveAdapter(input.registry, item) }));
+    const gated = gatedOutcomes(input.registry, new Set(resolved.flatMap(({ hit }) => (hit ? [hit.adapter.id] : []))), wanted);
+    if (wanted !== undefined && gated.length === 0) {
+        const valid = new Set();
+        for (const { item, hit } of resolved) {
+            valid.add(item.provider.toLowerCase());
+            if (hit)
+                valid.add(hit.adapter.id);
+        }
+        if (!valid.has(wanted))
+            throw new UnknownSyncAdapterError(input.adapter, [...valid].sort());
+    }
+    const selected = resolved.filter(({ item, hit }) => wanted === undefined || item.provider.toLowerCase() === wanted || hit?.adapter.id === wanted);
+    const planned = [];
+    const skipped = [];
+    for (const { item, hit } of selected) {
+        const blank = { connectionId: null, appName: null, landed: 0, duplicates: 0 };
+        if (!hit) {
+            skipped.push({
+                ...blank,
+                adapter: item.provider,
+                provider: item.provider,
+                status: "unavailable",
+                message: UNAVAILABLE_ADAPTER_MESSAGE,
+            });
+            continue;
+        }
+        const scopeProvider = item.hotChannel.tokenScope.provider.toLowerCase();
+        if (VAULT_TOKEN_PROVIDERS.has(scopeProvider)) {
+            const companions = companionApps(apps, hit.adapter.companionProviders ?? []);
+            const entry = { provider: hit.key };
+            if (companions.length > 0)
+                entry.companionConnectionIds = companions.map((app) => app.connectionId);
+            planned.push({ entry, item, adapter: hit.adapter, app: null, companions });
+            continue;
+        }
+        const names = new Set([hotChannelProviderKey(scopeProvider), hotChannelProviderKey(item.provider)]);
+        const matches = apps.filter((app) => names.has(hotChannelProviderKey(app.provider)));
+        if (matches.length === 0) {
+            skipped.push({
+                ...blank,
+                adapter: hit.adapter.id,
+                provider: item.provider,
+                status: "no-connection",
+                message: `no usable ${item.displayName ?? item.provider} connection; connect one with: hq integrations connect ${item.provider}`,
+            });
+            continue;
+        }
+        if (hit.adapter.transport === "push") {
+            // The push buffer is per person, not per connection: drain it once.
+            planned.push({ entry: { provider: hit.key }, item, adapter: hit.adapter, app: null });
+            continue;
+        }
+        for (const app of matches) {
+            planned.push({ entry: { provider: hit.key, connectionId: app.connectionId }, item, adapter: hit.adapter, app });
+        }
+    }
+    const reconnects = new Map();
+    const appsByConnection = new Map();
+    for (const p of planned) {
+        if (p.app)
+            appsByConnection.set(p.app.connectionId, p.app);
+        for (const app of p.companions ?? [])
+            appsByConnection.set(app.connectionId, app);
+    }
+    let results = [];
+    if (planned.length > 0) {
+        const sync = await runHotChannelSync({
+            trigger: input.trigger ?? "on-demand",
+            ...(input.catchUp === undefined ? {} : { catchUp: input.catchUp }),
+            ...(input.signalsGenerated ? { signalsGenerated: input.signalsGenerated } : {}),
+            ...(input.beforeWrite ? { beforeWrite: input.beforeWrite } : {}),
+            registry: input.registry,
+            catalog: planned.map((p) => p.entry),
+            vaultRoot: input.vaultRoot,
+            personUid: input.personUid,
+            personKey: input.personKey,
+            cursorStore: sourcesOnlyCursorStore(input.vaultRoot, input.now),
+            gatewayFor: (entry) => {
+                const app = entry.connectionId ? appsByConnection.get(entry.connectionId) : undefined;
+                return app ? gatewayFor(app, input.deps, reconnects) : undefined;
+            },
+            ...(input.now ? { now: input.now } : {}),
+            ...(input.runId ? { runId: input.runId } : {}),
+            ...(input.maxPagesPerAdapter ? { maxPagesPerAdapter: input.maxPagesPerAdapter } : {}),
+        });
+        report.runId = sync.runId;
+        report.entries = sync.entries;
+        results = sync.results;
+    }
+    planned.forEach((p, i) => {
+        const result = results[i];
+        const failed = !result || result.error !== undefined;
+        const outcome = {
+            adapter: p.adapter.id,
+            provider: p.item.provider,
+            connectionId: p.app?.connectionId ?? null,
+            appName: p.app?.name ?? null,
+            status: failed ? "failed" : "ok",
+            landed: result?.landed ?? 0,
+            duplicates: result?.duplicates ?? 0,
+            message: result?.error?.message ?? null,
+        };
+        if (failed && p.app) {
+            const reason = reconnects.get(p.app.connectionId) ?? (p.app.status === "needs-attention" ? "revoked" : undefined);
+            if (reason)
+                outcome.reconnect = { reason, prompt: reconnectPrompt(p.app, reason) };
+        }
+        report.outcomes.push(outcome);
+    });
+    report.outcomes.push(...skipped, ...gated);
+    if (report.outcomes.some((o) => o.status === "failed"))
+        report.exitCode = 1;
+    return report;
+}
+//# sourceMappingURL=run.js.map

package/dist/lib/hot-channels/signals-pass.d.ts

@@ -0,0 +1,150 @@
+/**
+ * The local signals pass (US-011). After a hot-channel run lands sources, the
+ * pass takes the run's landed documents through the ontology worklist, asks
+ * `claude -p` for signals one document at a time, and writes those signals to
+ * `companies/{co}/signals/`. It returns the count for the run ledger.
+ *
+ * A landed document with both `payload_ref` and `raw_ref` is a pointer (the
+ * meetings, Slack and Attio adapters land these). For it, claude gets the
+ * pointer followed by the document `payload_ref` names, capped at
+ * MAX_PAYLOAD_BYTES. A payload outside `sources/`, missing or unreadable falls
+ * back to the pointer alone, and the reason is warned and kept on the signal.
+ *
+ * Billing: policy hq-no-headless-print-subscription-billing forbids headless
+ * `claude -p` in general. This is its allowed case, per the owner decision of
+ * 2026-10-21: the owner's own `claude` login, on their own machine, in a
+ * bounded single-turn call. Cloud Claude is not the bot brain, and no model is
+ * called from the poller itself. Do not reuse this pass for a shared, fleet or
+ * hosted identity.
+ */
+import type { HotChannelRunResult, WriteGuard } from "./loop.js";
+/** Ledger `error` values a failed pass records. */
+export type SignalsPassErrorCode = "claude-logged-out" | "claude-timeout" | "claude-bad-output";
+/**
+ * A pass failure the run ledger records as `status: failed` with `error` set
+ * to the code. Any other error thrown from the pass is a crash.
+ */
+export declare class SignalsPassError extends Error {
+    readonly code: SignalsPassErrorCode;
+    constructor(code: SignalsPassErrorCode, message: string);
+}
+/** Signal types the pass accepts; the same type folders existing signals use. */
+export declare const SIGNAL_TYPES: readonly ["action_item", "commitment", "decision", "key_point", "participant_contribution", "question", "risk", "summary"];
+export type SignalType = (typeof SIGNAL_TYPES)[number];
+/**
+ * Flags that cut the signals call off from everything but the model: no
+ * built-in tools, no MCP servers, and no user, project or local settings (so
+ * user hooks and permission rules do not apply). The documents are untrusted
+ * provider content, so a prompt injection must have nothing to call.
+ * `--safe-mode` also stops CLAUDE.md and user memory from loading, so private
+ * context never reaches a prompt the documents can steer. `--bare` would do the
+ * same but reads only ANTHROPIC_API_KEY, which breaks subscription (OAuth)
+ * sign-in; `--safe-mode` keeps auth working (checked on Claude Code 2.1.308).
+ */
+export declare const CLAUDE_ISOLATION_ARGS: readonly string[];
+/** Per-document `claude -p` budget (policy indigo-executors-bound-all-waits). */
+export declare const DEFAULT_SIGNALS_TIMEOUT_MS = 120000;
+/** Budget for the `claude auth status` preflight. */
+export declare const AUTH_PREFLIGHT_TIMEOUT_MS = 10000;
+/** Budget for one worklist script call. */
+export declare const WORKLIST_TIMEOUT_MS = 60000;
+/** Documents one pass sends to claude across all adapters of a run. */
+export declare const DEFAULT_MAX_SIGNAL_DOCS = 20;
+/** Payload bytes sent to claude per document (200 KB). A longer payload is cut with a marker. */
+export declare const MAX_PAYLOAD_BYTES: number;
+export interface BoundedRun {
+    code: number | null;
+    stdout: string;
+    stderr: string;
+    timedOut: boolean;
+    /** Set when the process could not start (for example ENOENT). */
+    spawnError?: string;
+}
+/**
+ * Run a command with a hard timeout. The child leads its own process group;
+ * on timeout the whole group gets SIGTERM, then SIGKILL after a short grace
+ * (policy indigo-subprocess-wrapping-qmd-use-killpg-on-timeout), so a node
+ * child of `claude` cannot outlive the call.
+ */
+export declare function runBounded(command: string, args: readonly string[], options: {
+    timeoutMs: number;
+    input?: string;
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+}): Promise<BoundedRun>;
+export interface ClaudeSignalsPassOptions {
+    hqRoot: string;
+    company: string;
+    /** The `claude` CLI; resolved on PATH by default. */
+    claudeBin?: string;
+    timeoutMs?: number;
+    authTimeoutMs?: number;
+    maxDocs?: number;
+    /** Defaults to `{hqRoot}/core/scripts/ontology-source-worklist.sh`. */
+    worklistScript?: string;
+    /** Defaults to the shipped `prompts/signals-pass.md`. */
+    promptFile?: string;
+    now?: () => Date;
+    env?: NodeJS.ProcessEnv;
+    /** Where payload fallbacks are reported. Defaults to one line on stderr. */
+    warn?: (message: string) => void;
+}
+/** Why the pass sent claude the pointer alone. */
+export type PayloadFallbackReason = "payload-out-of-bounds" | "payload-missing" | "payload-unreadable";
+/** What the pass sends claude for one landed document. */
+export interface SignalsInput {
+    text: string;
+    /** Set when the payload was read and appended. */
+    payloadRef?: string;
+    /** Set when the document named a payload the pass could not use. */
+    fallback?: PayloadFallbackReason;
+    /** The `payload_ref` value behind a fallback. */
+    fallbackRef?: string;
+}
+interface WorkItem {
+    /** Vault-relative landed document, `sources/{channel}/{id}.md`. */
+    file: string;
+    channel: string;
+    principals: string[];
+    audienceKey: string;
+    audienceSource: string;
+    /** True when the worklist script listed the item and can mark it done. */
+    fromWorklist: boolean;
+}
+interface ParsedSignal {
+    type: SignalType;
+    title: string;
+    body: string;
+}
+export declare function defaultPromptFile(): string;
+/**
+ * The text claude gets for one landed document. A pointer (both `payload_ref`
+ * and `raw_ref` set) gets its payload appended after a separator line. Any
+ * other document is sent as landed: without `raw_ref`, `payload_ref` names the
+ * document's own `.raw.json` sidecar and the body is the content.
+ */
+export declare function buildSignalsInput(vaultRoot: string, file: string): Promise<SignalsInput>;
+/**
+ * Parse `claude -p --output-format json` output into signals. The envelope's
+ * `result` must itself be one JSON object, optionally inside a single code
+ * fence; nothing is scraped out of prose.
+ */
+export declare function parseClaudeSignals(stdout: string): ParsedSignal[];
+/** `sha256(source_ref \n type \n title)`: the same signal from the same source keeps its id. */
+export declare function signalId(sourceRef: string, type: string, title: string): string;
+/**
+ * Vault-relative directory for one signal type. Company-wide signals keep the
+ * existing `signals/{type}/` layout; person-scoped signals live under
+ * `signals/@{audienceKey}/{type}/`.
+ */
+export declare function signalTypeDir(key: string, type: SignalType): string;
+/** Write `signals/@{key}/_audience.yaml` once, when the partition is first created. */
+export declare function ensureAudienceFile(vaultRoot: string, item: Pick<WorkItem, "audienceKey" | "principals" | "audienceSource">): Promise<void>;
+/**
+ * Build the claude signals pass for one company. The pass keeps state for one
+ * run: the auth preflight runs once, and the document cap counts across every
+ * adapter of the run, so create a new pass per run.
+ */
+export declare function createClaudeSignalsPass(options: ClaudeSignalsPassOptions): (result: HotChannelRunResult, guard?: WriteGuard) => Promise<number>;
+export {};
+//# sourceMappingURL=signals-pass.d.ts.map