@damian87/omp 0.7.0 → 0.9.2

package/dist/src/gateway/notify.js

@@ -0,0 +1,261 @@
+/**
+ * Outbound Slack notifier — Hermes-style. No daemon. No socket. Each call is
+ * a stateless POST to Slack's REST API.
+ *
+ * Resolution model (mirrors apps/hermes-agent/tools/send_message_tool.py):
+ *  1. Caller passes `target` OR we read `SLACK_HOME_CHANNEL` from env.
+ *  2. If the resolved Slack ID is a user-id (U…), we call
+ *     `conversations.open` once to get the corresponding D… IM channel.
+ *  3. POST to `chat.postMessage` with the (D…/C…/G…) channel id.
+ *
+ * Retry: bounded exponential backoff on 429 (rate limit) and 5xx. Other Slack
+ * errors return immediately with the typed reason code so callers (cron) can
+ * record dropped payloads to a side log without hammering Slack.
+ */
+import { parseTarget, parseSlackRef } from "./target-parser.js";
+const SLACK_POST_URL = "https://slack.com/api/chat.postMessage";
+const SLACK_OPEN_URL = "https://slack.com/api/conversations.open";
+const DEFAULT_TIMEOUT_MS = 10_000;
+const MAX_ATTEMPTS = 3;
+/**
+ * Send a Slack message. Library entry point — never throws. Returns a
+ * structured result so callers (cron / `/slack send` skill / CLI) decide
+ * how to surface or persist failures.
+ */
+export async function notify(opts, deps = {}) {
+    const env = deps.env ?? process.env;
+    const doFetch = deps.fetch ?? fetch;
+    const sleep = deps.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const text = (opts.text ?? "").toString();
+    if (!text.trim()) {
+        return { ok: false, code: "POST_FAILED", reason: "text is empty" };
+    }
+    const token = (env.SLACK_BOT_TOKEN ?? "").trim();
+    if (!token) {
+        return { ok: false, code: "MISSING_TOKEN", reason: "SLACK_BOT_TOKEN is not set" };
+    }
+    // 1. Resolve target.
+    let target;
+    if (opts.target && opts.target.trim()) {
+        const parsed = parseTarget(opts.target);
+        if (!parsed.ok)
+            return { ok: false, code: "BAD_TARGET", reason: parsed.error };
+        target = parsed.target;
+    }
+    else {
+        const home = (env.SLACK_HOME_CHANNEL ?? "").trim();
+        if (!home) {
+            return {
+                ok: false,
+                code: "MISSING_TARGET",
+                reason: "no --target and SLACK_HOME_CHANNEL is unset; set one via `omp env init` or pass --target slack:C0…",
+            };
+        }
+        const parsed = parseSlackRef(home);
+        if (!parsed.ok) {
+            return {
+                ok: false,
+                code: "BAD_HOME_CHANNEL",
+                reason: `SLACK_HOME_CHANNEL=${home}: ${parsed.error}`,
+            };
+        }
+        target = parsed.target;
+    }
+    // Validate an explicit --thread-ts the same way we validate :thread_ts
+    // suffixes in the target string. Without this, a typo via the flag path
+    // bypasses parser validation and Slack reports an opaque error at runtime.
+    if (opts.threadTs && !/^[0-9]+\.[0-9]+$/.test(opts.threadTs)) {
+        return {
+            ok: false,
+            code: "BAD_TARGET",
+            reason: `threadTs "${opts.threadTs}" is not a Slack timestamp (expected digits.digits)`,
+        };
+    }
+    // One absolute deadline for the whole notify call — shared across
+    // conversations.open + chat.postMessage so a U-target send can't quietly
+    // take 2× the documented budget.
+    const deadline = Date.now() + (opts.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+    // 2. If user-id, resolve to a DM channel via conversations.open.
+    let channelId = target.id;
+    let openedIm = false;
+    if (target.kind === "user") {
+        const opened = await openIm(target.id, { token, doFetch, sleep, deadline });
+        if (!opened.ok)
+            return opened;
+        channelId = opened.channel;
+        openedIm = true;
+    }
+    // 3. Post.
+    const threadTs = opts.threadTs ?? target.threadTs;
+    return await postMessage({
+        token,
+        channel: channelId,
+        text,
+        threadTs,
+        doFetch,
+        sleep,
+        openedIm,
+        deadline,
+    });
+}
+async function openIm(userId, args) {
+    const r = await callSlack({
+        url: SLACK_OPEN_URL,
+        body: { users: userId },
+        ...args,
+    });
+    if (!r.ok) {
+        if (r.code === "RATE_LIMITED" || r.code === "TIMEOUT" || r.code === "NETWORK_ERROR") {
+            return r;
+        }
+        return { ok: false, code: "OPEN_FAILED", reason: r.reason };
+    }
+    const channel = r.payload?.channel?.id;
+    if (!channel) {
+        return { ok: false, code: "OPEN_FAILED", reason: "conversations.open returned no channel.id" };
+    }
+    return { ok: true, channel };
+}
+async function postMessage(args) {
+    const body = {
+        channel: args.channel,
+        text: args.text,
+    };
+    if (args.threadTs)
+        body.thread_ts = args.threadTs;
+    const r = await callSlack({ url: SLACK_POST_URL, body, ...args });
+    if (!r.ok)
+        return r;
+    const ts = r.payload?.ts ?? "";
+    return { ok: true, channel: args.channel, ts, openedIm: args.openedIm };
+}
+/**
+ * Single Slack API call with bounded retry. Treats 429 + 5xx as retryable
+ * (exponential backoff bounded by `timeoutMs`). Slack-level `ok:false`
+ * payloads return immediately as POST_FAILED — those are deterministic
+ * (invalid token / channel_not_found / not_in_channel etc).
+ */
+async function callSlack(args) {
+    for (let attempt = 0; attempt < MAX_ATTEMPTS; attempt++) {
+        const remaining = args.deadline - Date.now();
+        if (remaining <= 0) {
+            return { ok: false, code: "TIMEOUT", reason: `gave up after deadline` };
+        }
+        let res;
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            res = await args.doFetch(args.url, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json; charset=utf-8",
+                    Authorization: `Bearer ${args.token}`,
+                },
+                body: JSON.stringify(args.body),
+                signal: AbortSignal.timeout(Math.min(remaining, 5_000)),
+            });
+        }
+        catch (err) {
+            const msg = redact(err instanceof Error ? err.message : String(err), args.token);
+            if (/abort|timeout/i.test(msg)) {
+                return { ok: false, code: "TIMEOUT", reason: msg };
+            }
+            // Network blip — try again if we have budget.
+            const sleepMs = Math.min(backoffMs(attempt), Math.max(args.deadline - Date.now() - 50, 0));
+            if (attempt < MAX_ATTEMPTS - 1 && sleepMs > 0) {
+                await args.sleep(sleepMs);
+                continue;
+            }
+            return { ok: false, code: "NETWORK_ERROR", reason: msg };
+        }
+        // 429 → wait per Retry-After header if present; otherwise exponential.
+        if (res.status === 429) {
+            const retryAfter = Number(res.headers.get("retry-after") ?? 1);
+            const sleepBudget = Math.max(args.deadline - Date.now() - 100, 0);
+            const sleepMs = Math.min(retryAfter * 1000, sleepBudget);
+            if (attempt < MAX_ATTEMPTS - 1 && sleepMs >= 0 && sleepBudget > 0) {
+                await args.sleep(sleepMs);
+                continue;
+            }
+            return { ok: false, code: "RATE_LIMITED", reason: `429 after ${attempt + 1} attempt(s)` };
+        }
+        // 5xx → retry.
+        if (res.status >= 500 && res.status < 600) {
+            const sleepMs = Math.min(backoffMs(attempt), Math.max(args.deadline - Date.now() - 50, 0));
+            if (attempt < MAX_ATTEMPTS - 1 && sleepMs > 0) {
+                await args.sleep(sleepMs);
+                continue;
+            }
+            return { ok: false, code: "POST_FAILED", reason: `slack ${res.status} after ${attempt + 1} attempt(s)` };
+        }
+        // Anything else: parse the body and dispatch on Slack's own ok flag.
+        let payload;
+        try {
+            payload = (await res.json());
+        }
+        catch {
+            return { ok: false, code: "POST_FAILED", reason: `slack ${res.status}: non-JSON response` };
+        }
+        if (payload.ok === true)
+            return { ok: true, payload };
+        // Slack's documented schema has `error` as a string, but proxies / WAFs /
+        // wrong endpoints can return object / array / null. Coerce defensively
+        // before redacting — the public contract is never-throws.
+        const rawError = payload.error;
+        const reasonRaw = coerceErrorReason(rawError);
+        const reason = redact(reasonRaw, args.token);
+        // Slack uses `ratelimited` (no underscore) for rate-limit errors when not
+        // surfaced as HTTP 429. Treat as RATE_LIMITED so callers can back off.
+        if (reasonRaw === "ratelimited" || reasonRaw === "rate_limited") {
+            return { ok: false, code: "RATE_LIMITED", reason };
+        }
+        return { ok: false, code: "POST_FAILED", reason };
+    }
+    return { ok: false, code: "POST_FAILED", reason: "exhausted retries" };
+}
+/**
+ * Coerce a Slack error field of unknown shape to a string. Slack documents
+ * `error: string`, but proxies/WAFs/mis-pointed endpoints can return objects,
+ * arrays, or null. We must NOT throw — the caller's never-throws guarantee
+ * is part of the public contract.
+ */
+function coerceErrorReason(raw) {
+    if (raw == null)
+        return "slack returned ok:false";
+    if (typeof raw === "string")
+        return raw;
+    if (typeof raw === "number" || typeof raw === "boolean")
+        return String(raw);
+    try {
+        return JSON.stringify(raw);
+    }
+    catch {
+        return "slack returned ok:false (unserializable error field)";
+    }
+}
+/**
+ * Strip the bot token (and Bearer-prefix patterns) from any string that's
+ * about to be returned in `reason` or logged. Cheap belt-and-braces guard:
+ * Slack itself never echoes our token, but a fetch / abort / DNS error could
+ * contain the request URL or headers depending on the runtime, and any such
+ * leak would land in the schedule runner's stderr log.
+ */
+function redact(s, token) {
+    let out = s;
+    if (token) {
+        // Replace literal token wherever it appears.
+        out = out.split(token).join("[REDACTED]");
+    }
+    // Strip generic Bearer-token patterns that some fetch errors include.
+    out = out.replace(/Bearer\s+[A-Za-z0-9-._~+/]+=*/g, "Bearer [REDACTED]");
+    // Strip Slack-format tokens that might appear in payloads. Covers:
+    //   xox[a/b/e/p/r/s]- (legacy access / bot / refresh / user / config / signing)
+    //   xapp-              (app-level tokens — what `omp gateway serve` uses)
+    out = out.replace(/xox[a-z]-[A-Za-z0-9-]+/gi, "[REDACTED]");
+    out = out.replace(/xapp-[A-Za-z0-9-]+/gi, "[REDACTED]");
+    return out;
+}
+function backoffMs(attempt) {
+    // 250ms, 500ms, 1000ms — bounded so a misbehaving Slack doesn't stall cron forever.
+    return Math.min(250 * 2 ** attempt, 1_000);
+}
+//# sourceMappingURL=notify.js.map

package/dist/src/gateway/notify.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"notify.js","sourceRoot":"","sources":["../../../src/gateway/notify.ts"],"names":[],"mappings":"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"}

package/dist/src/gateway/registry.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Connector registry — the seam where new connectors plug in. Today: slack
+ * only. To add Telegram/Discord/etc, register a factory here, drop a file
+ * under src/gateway/connectors/, and the CLI `--only <name>` picks it up.
+ */
+import type { Connector, ConnectorDoctor } from "./connector.js";
+export interface RegistryDeps {
+    /** Env overrides for tests; default reads process.env. */
+    env?: NodeJS.ProcessEnv;
+}
+export interface BuiltConnectors {
+    /** Live connectors to be started by the gateway runtime. */
+    connectors: Connector[];
+    /** Doctor probes — one per *potential* connector, started or not. */
+    doctors: ConnectorDoctor[];
+    /** Warnings encountered while building the registry (e.g. missing tokens). */
+    warnings: string[];
+}
+/**
+ * Build the set of connectors that should run given the current env. A
+ * connector that lacks its required env vars is reported as a doctor probe
+ * (so `gateway status` can show the gap) but is NOT added to `connectors`.
+ *
+ * `enabledNames` (from `--only`) further filters the set; passing undefined
+ * means "all auto-detected".
+ */
+export declare function buildConnectors(enabledNames: string[] | undefined, deps?: RegistryDeps): BuiltConnectors;
+/** Known connector names — used for `--only` validation messages. */
+export declare const KNOWN_CONNECTORS: readonly string[];

package/dist/src/gateway/registry.js

@@ -0,0 +1,37 @@
+import { createSlackConnector, slackDoctor, SLACK_CONNECTOR_NAME } from "./connectors/slack.js";
+import { loadSlackConfig } from "../slack/config.js";
+/**
+ * Build the set of connectors that should run given the current env. A
+ * connector that lacks its required env vars is reported as a doctor probe
+ * (so `gateway status` can show the gap) but is NOT added to `connectors`.
+ *
+ * `enabledNames` (from `--only`) further filters the set; passing undefined
+ * means "all auto-detected".
+ */
+export function buildConnectors(enabledNames, deps = {}) {
+    const env = deps.env ?? process.env;
+    const warnings = [];
+    const connectors = [];
+    const doctors = [];
+    // --- slack ---
+    const slackEnabled = enabledNames ? enabledNames.includes(SLACK_CONNECTOR_NAME) : true;
+    if (slackEnabled) {
+        let slackCfg = null;
+        let slackErr;
+        try {
+            slackCfg = loadSlackConfig(undefined, env);
+        }
+        catch (err) {
+            slackErr = err instanceof Error ? err.message : String(err);
+            warnings.push(`slack: ${slackErr}`);
+        }
+        if (slackCfg) {
+            connectors.push(createSlackConnector({ config: slackCfg }));
+        }
+        doctors.push(slackDoctor(slackCfg, slackErr));
+    }
+    return { connectors, doctors, warnings };
+}
+/** Known connector names — used for `--only` validation messages. */
+export const KNOWN_CONNECTORS = [SLACK_CONNECTOR_NAME];
+//# sourceMappingURL=registry.js.map

package/dist/src/gateway/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../../src/gateway/registry.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,oBAAoB,EAAE,WAAW,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAChG,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAgBrD;;;;;;;GAOG;AACH,MAAM,UAAU,eAAe,CAC7B,YAAkC,EAClC,OAAqB,EAAE;IAEvB,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,CAAC;IACpC,MAAM,QAAQ,GAAa,EAAE,CAAC;IAC9B,MAAM,UAAU,GAAgB,EAAE,CAAC;IACnC,MAAM,OAAO,GAAsB,EAAE,CAAC;IAEtC,gBAAgB;IAChB,MAAM,YAAY,GAAG,YAAY,CAAC,CAAC,CAAC,YAAY,CAAC,QAAQ,CAAC,oBAAoB,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IACvF,IAAI,YAAY,EAAE,CAAC;QACjB,IAAI,QAAQ,GAAG,IAAI,CAAC;QACpB,IAAI,QAA4B,CAAC;QACjC,IAAI,CAAC;YACH,QAAQ,GAAG,eAAe,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC;QAC7C,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,QAAQ,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YAC5D,QAAQ,CAAC,IAAI,CAAC,UAAU,QAAQ,EAAE,CAAC,CAAC;QACtC,CAAC;QACD,IAAI,QAAQ,EAAE,CAAC;YACb,UAAU,CAAC,IAAI,CAAC,oBAAoB,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC;QAC9D,CAAC;QACD,OAAO,CAAC,IAAI,CAAC,WAAW,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC;IAChD,CAAC;IAED,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC;AAC3C,CAAC;AAED,qEAAqE;AACrE,MAAM,CAAC,MAAM,gBAAgB,GAAsB,CAAC,oBAAoB,CAAC,CAAC"}

package/dist/src/gateway/runtime.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Gateway runtime. Starts a set of {@link Connector}s in parallel, blocks on
+ * SIGINT/SIGTERM, then stops them via Promise.allSettled so one failing stop
+ * cannot strand the rest.
+ *
+ * Signal handling is injectable so tests can drive shutdown without sending
+ * real signals to the test runner.
+ */
+import type { Connector, ConnectorStatus } from "./connector.js";
+export interface RunGatewayOptions {
+    /** Connectors to run. Order is preserved in status output. */
+    connectors: Connector[];
+    /**
+     * Returns a promise that resolves when the runtime should shut down.
+     * Default: resolves on SIGINT or SIGTERM.
+     */
+    waitForShutdown?: () => Promise<void>;
+    /** Logger; defaults to console.error so info lines never pollute stdout JSON. */
+    log?: (msg: string) => void;
+}
+export interface GatewayStatusReport {
+    ready: boolean;
+    connectors: Array<{
+        name: string;
+    } & ConnectorStatus>;
+}
+/**
+ * Compute a status snapshot for a set of connectors. Pure — no I/O. The
+ * aggregate `ready` is true only when every connector reports ready.
+ */
+export declare function getGatewayStatus(connectors: Connector[]): GatewayStatusReport;
+/**
+ * Resolve on SIGINT/SIGTERM. Exported so it can be tested without sending
+ * real signals to the test runner: tests inject a fake `proc` with the same
+ * shape as `process` and assert listener attach/detach.
+ */
+export declare function waitForSignals(proc?: Pick<NodeJS.Process, "off" | "once">, log?: (msg: string) => void): Promise<void>;
+/**
+ * Run the gateway until shutdown. Returns when all connectors have stopped.
+ * Throws if no connectors are provided — callers should fail loudly when their
+ * `--only` filter or env config produced an empty set.
+ */
+export declare function runGateway(opts: RunGatewayOptions): Promise<void>;
+/**
+ * Build a filtered list of connectors from a registry by name. Names not in
+ * the registry are reported back so the caller can decide whether to error.
+ */
+export declare function selectConnectors<T extends {
+    name: string;
+}>(registry: Record<string, () => T>, names: string[]): {
+    connectors: T[];
+    unknown: string[];
+};
+/**
+ * Parse a comma-separated `--only` value into a list of trimmed, non-empty
+ * connector names.
+ */
+export declare function parseOnlyFlag(value: string | undefined): string[] | undefined;

package/dist/src/gateway/runtime.js

@@ -0,0 +1,105 @@
+/**
+ * Compute a status snapshot for a set of connectors. Pure — no I/O. The
+ * aggregate `ready` is true only when every connector reports ready.
+ */
+export function getGatewayStatus(connectors) {
+    const rows = connectors.map((c) => {
+        const s = c.status();
+        return { name: c.name, ready: s.ready, detail: s.detail };
+    });
+    return { ready: rows.length > 0 && rows.every((r) => r.ready), connectors: rows };
+}
+/**
+ * Resolve on SIGINT/SIGTERM. Exported so it can be tested without sending
+ * real signals to the test runner: tests inject a fake `proc` with the same
+ * shape as `process` and assert listener attach/detach.
+ */
+export function waitForSignals(proc = process, log = (m) => console.error(m)) {
+    return new Promise((resolve) => {
+        const onSig = (sig) => {
+            // Detach both listeners so a second signal doesn't double-resolve.
+            proc.off("SIGINT", onSig);
+            proc.off("SIGTERM", onSig);
+            // Log to stderr so JSON consumers on stdout aren't disturbed.
+            log(`omp gateway: received ${sig}, shutting down…`);
+            resolve();
+        };
+        proc.once("SIGINT", onSig);
+        proc.once("SIGTERM", onSig);
+    });
+}
+/**
+ * Run the gateway until shutdown. Returns when all connectors have stopped.
+ * Throws if no connectors are provided — callers should fail loudly when their
+ * `--only` filter or env config produced an empty set.
+ */
+export async function runGateway(opts) {
+    const log = opts.log ?? ((m) => console.error(m));
+    const connectors = opts.connectors;
+    if (connectors.length === 0) {
+        throw new Error("no connectors configured — set tokens or pass --only <name>");
+    }
+    // Start all in parallel; surface per-connector failure but let the rest run.
+    // A reasonable default is "best-effort start": if one connector cannot come
+    // up, the others continue and `gateway status` reports the failure.
+    const startResults = await Promise.allSettled(connectors.map((c) => c.start()));
+    startResults.forEach((r, i) => {
+        if (r.status === "rejected") {
+            const msg = r.reason instanceof Error ? r.reason.message : String(r.reason);
+            log(`omp gateway: connector "${connectors[i].name}" failed to start: ${msg}`);
+        }
+        else {
+            log(`omp gateway: connector "${connectors[i].name}" ready`);
+        }
+    });
+    const ready = connectors.filter((_, i) => startResults[i].status === "fulfilled");
+    if (ready.length === 0) {
+        // Nothing came up. Even failed start()s may have allocated resources, and
+        // stop() is required to be idempotent — call it on every connector before
+        // surfacing the error, so the runtime upholds its own lifecycle contract.
+        await Promise.allSettled(connectors.map((c) => c.stop()));
+        throw new Error("all gateway connectors failed to start");
+    }
+    const wait = opts.waitForShutdown ?? (() => waitForSignals());
+    // try/finally guarantees stop() runs even if waitForShutdown rejects (e.g.
+    // an injected wait throws, or a signal handler propagates an error).
+    try {
+        await wait();
+    }
+    finally {
+        // Stop everything — including connectors that never started, since stop()
+        // is required to be idempotent.
+        await Promise.allSettled(connectors.map((c) => c.stop()));
+    }
+}
+/**
+ * Build a filtered list of connectors from a registry by name. Names not in
+ * the registry are reported back so the caller can decide whether to error.
+ */
+export function selectConnectors(registry, names) {
+    const unknown = [];
+    const connectors = [];
+    for (const name of names) {
+        const factory = registry[name];
+        if (!factory) {
+            unknown.push(name);
+            continue;
+        }
+        connectors.push(factory());
+    }
+    return { connectors, unknown };
+}
+/**
+ * Parse a comma-separated `--only` value into a list of trimmed, non-empty
+ * connector names.
+ */
+export function parseOnlyFlag(value) {
+    if (value === undefined)
+        return undefined;
+    const parts = value
+        .split(",")
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+    return parts.length === 0 ? undefined : parts;
+}
+//# sourceMappingURL=runtime.js.map

package/dist/src/gateway/runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.js","sourceRoot":"","sources":["../../../src/gateway/runtime.ts"],"names":[],"mappings":"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"}

package/dist/src/gateway/target-parser.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Parse outbound notification targets.
+ *
+ * Target grammar (Hermes-mirror — see apps/hermes-agent/tools/send_message_tool.py:21-46):
+ *
+ *   "<platform>:<ref>"   → explicit per-call target
+ *
+ * Bare-platform fallback (`<platform>` with no `:<ref>`) is NOT implemented in
+ * this parser. The notify() caller layer handles the "no target → env default"
+ * decision by passing undefined/empty as the target and reading
+ * `SLACK_HOME_CHANNEL` directly — it never calls `parseTarget("slack")`.
+ *
+ * For slice 1 the only platform is "slack". <ref> for slack is a 9+ char
+ * uppercase alphanumeric ID prefixed with one of:
+ *   C — public channel
+ *   G — private channel ("group")
+ *   D — direct message conversation
+ *   U — user (must be conversations.open'd to a D… before chat.postMessage;
+ *       the caller is responsible for that resolution)
+ *
+ * Optional thread suffix: "<ref>:<thread_ts>" pins the post to an existing
+ * thread in that conversation. Not all kinds support threading sensibly, but
+ * the parser accepts it for any non-user kind.
+ *
+ * NOT supported in this pass: user IDs with embedded thread suffixes (no
+ * coherent meaning until U→D resolution); Hermes-style multi-platform
+ * regexes for telegram/discord/feishu (those land in slice 2+).
+ */
+/** Slack ID after the `slack:` prefix. */
+export declare const SLACK_ID_RE: RegExp;
+/**
+ * Slack ID + optional thread suffix `:<thread_ts>`.
+ *
+ * `thread_ts` must look like Slack's canonical message timestamp shape
+ * (`<seconds>.<microseconds>` — digits-only). Anything else is rejected here
+ * so the CLI / schedule add validators catch typos before they reach Slack.
+ */
+export declare const SLACK_TARGET_RE: RegExp;
+export type SlackTargetKind = "channel" | "group" | "dm" | "user";
+export interface SlackTarget {
+    platform: "slack";
+    kind: SlackTargetKind;
+    /**
+     * The raw Slack ID (`C…`/`G…`/`D…`/`U…`). For user targets, the caller
+     * must resolve to a D-ID via conversations.open before posting.
+     */
+    id: string;
+    /** Optional `thread_ts` for threaded posts. */
+    threadTs?: string;
+}
+export type ParsedTarget = SlackTarget;
+export interface ParseError {
+    ok: false;
+    error: string;
+}
+export type ParseResult = {
+    ok: true;
+    target: ParsedTarget;
+} | ParseError;
+/**
+ * Parse a target string of the form `<platform>:<ref>`. Returns either a
+ * structured target or a friendly error. Pure — no I/O.
+ */
+export declare function parseTarget(raw: string): ParseResult;
+/**
+ * Parse just the slack-side `<ref>` (the part after `slack:`). Useful when a
+ * caller has already established platform context (e.g. `SLACK_HOME_CHANNEL`
+ * is set without a platform prefix).
+ */
+export declare function parseSlackRef(ref: string): ParseResult;
+/**
+ * Best-effort check for "looks like a Slack ID" without committing to a
+ * specific kind — used by config validators to nudge users about typos
+ * before any network call.
+ */
+export declare function looksLikeSlackId(value: string): boolean;