hypervibes 0.0.0-stage → 0.4.0

package/dist/db/subagent-schema.js

@@ -0,0 +1,79 @@
+import { sql } from "drizzle-orm";
+import { check, foreignKey, index, integer, primaryKey, sqliteTable, text, uniqueIndex } from "drizzle-orm/sqlite-core";
+import { hvAgents } from "./agent-schema.js";
+export const hvSubagents = sqliteTable("hv_subagents", {
+    id: text("id").primaryKey(),
+    agentId: text("agent_id").notNull().references(() => hvAgents.id, { onDelete: "cascade" }),
+    kind: text("kind", { enum: ["orchestrator", "worker"] }).notNull(),
+    name: text("name").notNull(),
+    description: text("description").notNull().default(""),
+    instructions: text("instructions").notNull(),
+    provider: text("provider").notNull(),
+    modelId: text("model_id").notNull(),
+    thinkingLevel: text("thinking_level").notNull().default(""),
+    tools: text("tools", { mode: "json" }).$type().notNull(),
+    triggers: text("triggers", { mode: "json" }).$type().notNull().default({ inboxEnabled: false, workerDelegates: [], researchSources: [], fills: false, orderChanges: false }),
+    templateOrigin: text("template_origin", { mode: "json" }).$type(),
+    enabled: integer("enabled", { mode: "boolean" }).notNull().default(true),
+    archived: integer("archived", { mode: "boolean" }).notNull().default(false),
+    delegatable: integer("delegatable", { mode: "boolean" }).notNull().default(true),
+    persistent: integer("persistent", { mode: "boolean" }).notNull().default(false),
+    conversationId: integer("conversation_id"),
+    schedule: text("schedule").notNull().default(""),
+    delaySeconds: integer("delay_seconds").notNull().default(1),
+    nextRunAt: integer("next_run_at"),
+    completion: text("completion", { enum: ["save", "notify", "wake"] }).notNull().default("wake"),
+    timeoutSeconds: integer("timeout_seconds").notNull().default(900),
+    createdAt: integer("created_at").notNull(),
+    updatedAt: integer("updated_at").notNull(),
+}, (t) => [
+    index("hv_subagents_agent_idx").on(t.agentId),
+    uniqueIndex("hv_subagents_identity_idx").on(t.agentId, t.id),
+    uniqueIndex("hv_subagents_main_idx").on(t.agentId).where(sql `${t.kind} = 'orchestrator'`),
+    check("hv_subagents_main_protected", sql `${t.kind} != 'orchestrator' OR (${t.enabled} = 1 AND ${t.archived} = 0 AND ${t.schedule} = '')`),
+]);
+export const hvSubagentRuns = sqliteTable("hv_subagent_runs", {
+    id: text("id").primaryKey(),
+    agentId: text("agent_id").notNull().references(() => hvAgents.id, { onDelete: "cascade" }),
+    subagentId: text("subagent_id").notNull().references(() => hvSubagents.id, { onDelete: "cascade" }),
+    requestId: text("request_id").notNull(),
+    source: text("source", { enum: ["manual", "schedule", "delegation", "event"] }).notNull(),
+    task: text("task").notNull(),
+    config: text("config", { mode: "json" }).$type().notNull(),
+    status: text("status", { enum: ["queued", "running", "completed", "failed", "cancelled", "skipped"] }).notNull().default("queued"),
+    taskId: integer("task_id"),
+    conversationId: integer("conversation_id"),
+    result: text("result").notNull().default(""),
+    createdAt: integer("created_at").notNull(),
+    finishedAt: integer("finished_at"),
+    reportedAt: integer("reported_at"),
+}, (t) => [
+    uniqueIndex("hv_subagent_runs_request_idx").on(t.agentId, t.requestId),
+    uniqueIndex("hv_subagent_runs_producer_idx").on(t.agentId, t.id, t.subagentId),
+    uniqueIndex("hv_subagent_runs_identity_idx").on(t.agentId, t.id),
+    uniqueIndex("hv_subagent_runs_active_idx").on(t.subagentId).where(sql `${t.status} IN ('queued', 'running')`),
+    index("hv_subagent_runs_history_idx").on(t.subagentId, t.createdAt),
+]);
+/** Activation windows are maintained atomically by the inbox migration's SQLite triggers. */
+export const hvWorkerSubscriptions = sqliteTable("hv_worker_subscriptions", {
+    subagentId: text("subagent_id").notNull().references(() => hvSubagents.id, { onDelete: "cascade" }),
+    eventType: text("event_type").notNull(),
+    sourceId: text("source_id").notNull(),
+    activatedAt: integer("activated_at").notNull(),
+}, (t) => [primaryKey({ columns: [t.subagentId, t.eventType, t.sourceId] })]);
+/** Application-owned inbox and request provenance; admission atomically links requests to runs. */
+export const hvWorkerRequests = sqliteTable("hv_worker_requests", {
+    id: text("id").primaryKey(),
+    agentId: text("agent_id").notNull().references(() => hvAgents.id, { onDelete: "cascade" }),
+    subagentId: text("subagent_id").notNull(),
+    eventKey: text("event_key").notNull(),
+    payload: text("payload", { mode: "json" }).$type().notNull(),
+    createdAt: integer("created_at").notNull(),
+    runId: text("run_id"),
+    discardedReason: text("discarded_reason"),
+}, (t) => [
+    foreignKey({ columns: [t.agentId, t.subagentId], foreignColumns: [hvSubagents.agentId, hvSubagents.id] }),
+    foreignKey({ columns: [t.agentId, t.runId, t.subagentId], foreignColumns: [hvSubagentRuns.agentId, hvSubagentRuns.id, hvSubagentRuns.subagentId] }),
+    uniqueIndex("hv_worker_requests_event_idx").on(t.agentId, t.subagentId, t.eventKey),
+    index("hv_worker_requests_pending_idx").on(t.subagentId, t.createdAt).where(sql `${t.runId} IS NULL AND ${t.discardedReason} IS NULL`),
+]);

package/dist/gateway/bridge-service.js

@@ -0,0 +1,223 @@
+import { sendTelegramNotification } from "./telegram/transport.js";
+import { NotificationDeliveryError } from "../notifications/delivery.js";
+import { randomUUID } from "node:crypto";
+import { AgentError } from "../agents/agent-input.js";
+import { bindGatewayChat, decryptGatewayToken, gatewayStatus, getGateway, listGateways } from "./gateway-store.js";
+import { PENDING_LINK_TTL_MS } from "./handlers.js";
+function describe(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/**
+ * Owns one gateway platform's endpoints. Event-driven lifecycle: configured
+ * gateways start once at startup, and later changes flow through `ensure()`
+ * and `removed()` from the settings mutations.
+ */
+export class GatewayBridge {
+    db;
+    agents;
+    key;
+    connector;
+    options;
+    endpoints = new Map();
+    startup;
+    stoppingEndpoints = new Set();
+    pending = new Map();
+    errors = new Map();
+    started = false;
+    stopping = false;
+    closing;
+    constructor(db, agents, key, connector, options = {}) {
+        this.db = db;
+        this.agents = agents;
+        this.key = key;
+        this.connector = connector;
+        this.options = options;
+    }
+    get type() { return this.connector.type; }
+    /** The active encryption key; gateway credentials require one on the server. */
+    requireKey() {
+        if (!this.key)
+            throw new AgentError(`${this.connector.label} gateways require AGENTS_ENCRYPTION_KEY on the server.`, 503);
+        return this.key;
+    }
+    /** Loads this platform's configured gateways once and starts their endpoints. */
+    start() {
+        if (this.started || this.stopping)
+            return;
+        this.started = true;
+        this.startup = listGateways(this.db, this.type).then(async (rows) => { await Promise.all(rows.map((row) => this.startEndpoint(row))); })
+            .catch((error) => { if (!this.stopping)
+            this.options.logger?.error(`Unable to start ${this.connector.label} bridge: ${describe(error)}`); });
+    }
+    /** Starts the endpoint after a gateway row was created, if it is not running yet. */
+    async ensure(agentId) {
+        if (this.stopping || this.endpoints.has(agentId))
+            return;
+        const row = await getGateway(this.db, agentId, this.type);
+        if (row)
+            await this.startEndpoint(row);
+    }
+    /** Stops the endpoint and drops pending links: disconnect or agent deletion. */
+    async removed(agentId) {
+        for (const [token, link] of this.pending)
+            if (link.agentId === agentId)
+                this.pending.delete(token);
+        this.errors.delete(agentId);
+        const endpoint = this.endpoints.get(agentId);
+        if (!endpoint)
+            return;
+        this.endpoints.delete(agentId);
+        await this.stopEndpoint(endpoint);
+    }
+    /** Creates or returns the owner's pending link token and its deep-link URL. */
+    async startLink(agentId, userId) {
+        const row = await getGateway(this.db, agentId, this.type);
+        if (!row)
+            throw new AgentError(`Add a ${this.connector.label} bot token first.`, 400);
+        let existing;
+        for (const [token, link] of this.pending) {
+            if (link.agentId !== agentId)
+                continue;
+            if (link.userId !== userId || link.expiresAt <= Date.now())
+                this.pending.delete(token);
+            else
+                existing = { ...link, token };
+        }
+        const link = existing ?? { token: randomUUID(), agentId, userId, expiresAt: Date.now() + PENDING_LINK_TTL_MS };
+        this.pending.set(link.token, link);
+        return this.connector.linkUrl(row, link.token);
+    }
+    /** A queued notification is bound to its original destination, never a newly linked chat. */
+    async sendNotification(target, text, signal) {
+        if (this.stopping)
+            throw new NotificationDeliveryError("Gateway is shutting down");
+        const row = await getGateway(this.db, target.agentId, this.type);
+        if (!row || row.chatId !== target.chatId || row.botTokenHash !== target.botTokenHash)
+            throw new NotificationDeliveryError("Telegram destination changed", true, undefined, true);
+        const token = decryptGatewayToken(this.key, row);
+        if (!token)
+            throw new NotificationDeliveryError("Telegram token cannot be decrypted; reconnect Telegram in settings", true);
+        return sendTelegramNotification(token, target.chatId, text, signal);
+    }
+    /** Render-safe gateway state for the settings page. */
+    async status(agentId) {
+        const row = await getGateway(this.db, agentId, this.type);
+        return gatewayStatus(row, this.errors.get(agentId));
+    }
+    /** Stops every endpoint and drops all link state. */
+    close() {
+        return this.closing ??= (async () => {
+            this.stopping = true;
+            // An initial gateway query must finish before the runtime closes its database.
+            await this.startup;
+            const endpoints = [...this.endpoints.values()];
+            this.endpoints.clear();
+            this.pending.clear();
+            await Promise.all(endpoints.map((endpoint) => this.stopEndpoint(endpoint)));
+            while (this.stoppingEndpoints.size)
+                await Promise.all([...this.stoppingEndpoints]);
+        })();
+    }
+    async startEndpoint(row) {
+        if (this.stopping || this.endpoints.has(row.agentId))
+            return;
+        const token = decryptGatewayToken(this.key, row);
+        if (!token) {
+            this.errors.set(row.agentId, "The bot token cannot be decrypted with the active encryption key. Re-add the bot token in settings.");
+            this.options.logger?.warn(`Bot token for agent ${row.agentId} cannot be decrypted; endpoint not started`);
+            return;
+        }
+        const state = {
+            endpoint: this.connector.createEndpoint(token, (message) => {
+                if (!this.stopping && this.endpoints.get(row.agentId) === state && !state.lifetime.signal.aborted) {
+                    this.track(state, this.receive(row.agentId, message, state));
+                }
+            }, this.options.logger),
+            lifetime: new AbortController(), tasks: new Set(),
+        };
+        this.endpoints.set(row.agentId, state);
+        this.errors.delete(row.agentId);
+        void state.endpoint.start().then(() => {
+            void this.stopEndpoint(state);
+            if (this.endpoints.get(row.agentId) === state)
+                this.endpoints.delete(row.agentId);
+        }, (error) => {
+            const expected = this.stopping || state.lifetime.signal.aborted;
+            void this.stopEndpoint(state);
+            if (this.endpoints.get(row.agentId) !== state)
+                return;
+            this.endpoints.delete(row.agentId);
+            if (expected)
+                return;
+            this.errors.set(row.agentId, describe(error));
+            this.options.logger?.warn(`${this.connector.label} endpoint for agent ${row.agentId} stopped: ${describe(error)}`);
+        });
+    }
+    workspace(state) {
+        return {
+            signal: state.lifetime.signal,
+            track: (task) => this.track(state, task),
+            loadGateway: (agentId) => getGateway(this.db, agentId, this.type),
+            bindChat: (agentId, chatId, chatUsername) => bindGatewayChat(this.db, agentId, this.type, chatId, chatUsername),
+            consumeLink: (token) => this.consumeLink(token),
+            bridge: async (agentId) => {
+                state.lifetime.signal.throwIfAborted();
+                const handle = await this.agents.bridge(agentId);
+                state.lifetime.signal.throwIfAborted();
+                return handle;
+            },
+            logger: this.options.logger,
+        };
+    }
+    /** One-shot link consumption; the token dies with its first use or its expiry. */
+    consumeLink(token) {
+        const link = this.pending.get(token);
+        if (!link)
+            return { status: "unknown" };
+        this.pending.delete(token);
+        if (link.expiresAt <= Date.now())
+            return { status: "expired" };
+        return { status: "ok", agentId: link.agentId };
+    }
+    track(state, task) {
+        state.tasks.add(task);
+        void task.then(() => state.tasks.delete(task), () => state.tasks.delete(task));
+    }
+    stopEndpoint(state) {
+        if (state.closing)
+            return state.closing;
+        const closing = state.closing = (async () => {
+            state.lifetime.abort();
+            const stopped = state.endpoint.stop().catch((error) => {
+                this.options.logger?.warn(`${this.connector.label} endpoint stop failed: ${describe(error)}`);
+            });
+            // A message handler can register a reply forwarder while it finishes.
+            while (state.tasks.size)
+                await Promise.allSettled([...state.tasks]);
+            await stopped;
+        })();
+        this.stoppingEndpoints.add(closing);
+        void closing.then(() => this.stoppingEndpoints.delete(closing), () => this.stoppingEndpoints.delete(closing));
+        return closing;
+    }
+    async receive(agentId, message, state) {
+        const lifetime = state.lifetime.signal;
+        const sender = {
+            sendText: async (chatId, text, signal) => {
+                lifetime.throwIfAborted();
+                return state.endpoint.sendText(chatId, text, signal ? AbortSignal.any([signal, lifetime]) : lifetime);
+            },
+            sendTyping: async (chatId, signal) => {
+                lifetime.throwIfAborted();
+                return state.endpoint.sendTyping(chatId, signal ? AbortSignal.any([signal, lifetime]) : lifetime);
+            },
+        };
+        try {
+            await this.connector.handle(agentId, message, this.workspace(state), sender);
+        }
+        catch (error) {
+            if (!lifetime.aborted)
+                this.options.logger?.warn(`${this.connector.label} message handling for agent ${agentId} failed: ${describe(error)}`);
+        }
+    }
+}

package/dist/gateway/gateway-store.js

@@ -0,0 +1,77 @@
+import { and, eq } from "drizzle-orm";
+import { createHash } from "node:crypto";
+import { AgentError } from "../agents/agent-input.js";
+import { hvGateways } from "../db/gateway-schema.js";
+import { decryptSecret, encryptSecret } from "../hyperliquid/crypto.js";
+/** Deterministic token fingerprint backing the cross-Agent uniqueness constraint. */
+export function hashBotToken(token) {
+    return createHash("sha256").update(token).digest("hex");
+}
+export async function getGateway(db, agentId, type) {
+    return db.select().from(hvGateways).where(and(eq(hvGateways.agentId, agentId), eq(hvGateways.type, type))).get();
+}
+/** Every configured gateway of one type; token presence means the endpoint should run. */
+export async function listGateways(db, type) {
+    return db.select().from(hvGateways).where(eq(hvGateways.type, type)).all();
+}
+/** The bot token of one configured gateway; undefined when the encryption key is missing or changed. */
+export function decryptGatewayToken(key, row) {
+    if (!key || row.keyId !== key.id)
+        return undefined;
+    try {
+        return decryptSecret(key, row.botTokenCiphertext);
+    }
+    catch {
+        return undefined;
+    }
+}
+function uniqueTokenViolation(error) {
+    let current = error;
+    for (let depth = 0; current !== null && typeof current === "object" && depth < 5; depth++) {
+        const message = current.message;
+        if (typeof message === "string" && message.includes("UNIQUE constraint failed") && message.includes("bot_token_hash"))
+            return true;
+        current = current.cause;
+    }
+    return false;
+}
+/** Stores a newly validated bot token; the token hash stops two Agents sharing one bot. */
+export async function saveGatewayToken(db, key, agentId, type, token, botUsername) {
+    const values = {
+        botTokenCiphertext: Buffer.from(encryptSecret(key, token)),
+        botTokenHash: hashBotToken(token),
+        keyId: key.id,
+        botUsername,
+        updatedAt: Date.now(),
+    };
+    try {
+        await db.insert(hvGateways).values({ agentId, type, ...values }).run();
+    }
+    catch (error) {
+        if (uniqueTokenViolation(error))
+            throw new AgentError("This bot is already linked to another Agent.", 409);
+        throw error;
+    }
+}
+/** Persists the chat that completed the link flow; false when no gateway row exists. */
+export async function bindGatewayChat(db, agentId, type, chatId, chatUsername) {
+    const row = await getGateway(db, agentId, type);
+    if (!row)
+        return false;
+    await db.update(hvGateways).set({ chatId, chatUsername, updatedAt: Date.now() }).where(and(eq(hvGateways.agentId, agentId), eq(hvGateways.type, type))).run();
+    return true;
+}
+/** Removes the bot token and binding; false when no gateway row exists. */
+export async function deleteGateway(db, agentId, type) {
+    const row = await getGateway(db, agentId, type);
+    if (!row)
+        return false;
+    await db.delete(hvGateways).where(and(eq(hvGateways.agentId, agentId), eq(hvGateways.type, type))).run();
+    return true;
+}
+/** Status view of a gateway row, extended with an optional runtime endpoint error. */
+export function gatewayStatus(row, error) {
+    if (!row)
+        return { hasToken: false, connected: false, botUsername: null, chatId: null, chatUsername: null };
+    return { hasToken: true, connected: row.chatId !== null, botUsername: row.botUsername, chatId: row.chatId, chatUsername: row.chatUsername, ...(error ? { error } : {}) };
+}

package/dist/gateway/handlers.js

@@ -0,0 +1,122 @@
+import { awaitWithContext, BACKGROUND_CONTEXT as context, withAbortSignal } from "@earendil-works/chord/context";
+import { randomUUID } from "node:crypto";
+import { setTimeout as delay } from "node:timers/promises";
+import { isAgentError } from "../agents/agent-input.js";
+/** A deep-link token is valid for ten minutes, matching the legacy gateway. */
+export const PENDING_LINK_TTL_MS = 10 * 60 * 1000;
+/** How long the bridge forwards one turn's reply before giving up on it. */
+export const REPLY_TIMEOUT_MS = 30 * 60 * 1000;
+/** The typing action expires after ~5 seconds and is refreshed while a turn runs. */
+const TYPING_REFRESH_MS = 4500;
+/** Chunked for the platform's message limit; split by code points so emoji survive. */
+export function chunkText(text, max) {
+    const characters = [...text];
+    const chunks = [];
+    for (let index = 0; index < characters.length; index += max)
+        chunks.push(characters.slice(index, index + max).join(""));
+    return chunks.length ? chunks : [""];
+}
+/** A public, bounded error message; AgentError and plain reasons carry operator-facing text. */
+export function bridgeErrorText(error) {
+    const detail = typeof error === "string" ? error : isAgentError(error) || error instanceof Error ? error.message : "Unknown error";
+    return `I couldn't process that message: ${[...detail].slice(0, 1000).join("")}`;
+}
+/**
+ * The operator-facing text of a terminal submission. `reason` is a machine code such as `model_error`;
+ * `detail` carries the provider's actual message, which is what an operator can act on.
+ */
+export function submissionErrorText(settled) {
+    const detail = typeof settled.detail === "string" ? settled.detail.trim() : "";
+    return detail || settled.reason;
+}
+/** Refreshes typing only while forwarding owns it; joins any in-flight typing request. */
+async function withTyping(sender, chatId, operation, lifetime) {
+    const stop = new AbortController();
+    const signal = lifetime ? AbortSignal.any([stop.signal, lifetime]) : stop.signal;
+    const typing = (async () => {
+        while (!signal.aborted) {
+            await sender.sendTyping(chatId, signal).catch(() => undefined);
+            if (!signal.aborted)
+                await delay(TYPING_REFRESH_MS, undefined, { signal }).catch(() => undefined);
+        }
+    })();
+    try {
+        await operation();
+    }
+    finally {
+        stop.abort();
+        await typing;
+    }
+}
+/** Forwards the assistant reply once the submitted turn settles. */
+export async function forwardReply(workspace, sender, chatId, handle, submission) {
+    const timeout = workspace.replyTimeoutMs ?? REPLY_TIMEOUT_MS;
+    const expired = new AbortController();
+    const timer = setTimeout(() => expired.abort(), timeout);
+    const signal = workspace.signal ? AbortSignal.any([workspace.signal, expired.signal]) : expired.signal;
+    try {
+        await withTyping(sender, chatId, async () => {
+            let settled;
+            try {
+                signal.throwIfAborted();
+                const invocation = withAbortSignal(signal, context);
+                settled = await awaitWithContext(submission.wait(invocation), invocation);
+            }
+            catch (error) {
+                if (workspace.signal?.aborted)
+                    return;
+                if (!expired.signal.aborted)
+                    throw error;
+                await sender.sendText(chatId, "This response is taking longer than expected. The turn is still running; continue in the web dashboard.", workspace.signal);
+                return;
+            }
+            workspace.signal?.throwIfAborted();
+            if (settled.status === "unanswered" || settled.entry === undefined || settled.answer === undefined) {
+                await sender.sendText(chatId, bridgeErrorText(settled.status === "unanswered" ? submissionErrorText(settled) : "The turn produced no reply"), workspace.signal);
+                return;
+            }
+            const replies = await handle.replyText(settled.entry, settled.answer);
+            for (const reply of replies) {
+                workspace.signal?.throwIfAborted();
+                await sender.sendText(chatId, reply, workspace.signal);
+            }
+        }, workspace.signal);
+    }
+    catch (error) {
+        if (!workspace.signal?.aborted)
+            throw error;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/** Submits plain chat text to the Agent's main conversation and forwards the reply in the background. */
+export async function submitChat(agentId, chatId, text, workspace, sender) {
+    let handle;
+    let submission;
+    try {
+        workspace.signal?.throwIfAborted();
+        handle = await workspace.bridge(agentId);
+        workspace.signal?.throwIfAborted();
+        submission = await handle.submit(text, randomUUID());
+    }
+    catch (error) {
+        if (!workspace.signal?.aborted)
+            await sender.sendText(chatId, bridgeErrorText(error), workspace.signal);
+        return;
+    }
+    if (workspace.signal?.aborted)
+        return;
+    const status = await submission.status(context).catch(() => undefined);
+    if (workspace.signal?.aborted)
+        return;
+    if (status?.status === "queued")
+        await sender.sendText(chatId, "Message queued. It will send when the current turn finishes.", workspace.signal);
+    // The turn runs in the background so the next message is picked up immediately,
+    // matching the legacy gateway's fire-and-forget reply forwarder.
+    const forwarding = forwardReply(workspace, sender, chatId, handle, submission).catch((error) => {
+        if (!workspace.signal?.aborted)
+            workspace.logger?.warn("Gateway reply forwarding failed", error);
+    });
+    workspace.track?.(forwarding);
+}

package/dist/gateway/telegram/connector.js

@@ -0,0 +1,115 @@
+import { bridgeErrorText, submitChat } from "../handlers.js";
+import { grammyEndpoint } from "./transport.js";
+/** Splits a `/name[@bot] args` message; undefined for plain text. */
+function parseCommand(text) {
+    const match = /^\/([a-zA-Z]+)(?:@[a-zA-Z0-9_]+)?(?:\s+([\s\S]*))?$/.exec(text);
+    const name = match?.[1]?.toLowerCase();
+    if (!name)
+        return undefined;
+    return { name, arg: (match?.[2] ?? "").trim() };
+}
+/** The `/start <token>` payload of a link deep link; undefined for other messages. */
+function extractStartPayload(text) {
+    const command = parseCommand(text);
+    if (command?.name !== "start")
+        return undefined;
+    return command.arg || undefined;
+}
+const HELP_TEXT = [
+    "Commands:",
+    "/reset — start a fresh conversation",
+    "/stop — stop the active turn",
+    "/compact — compact the conversation",
+    "/help — show this help",
+    "Everything else goes to this Agent's main conversation.",
+].join("\n");
+async function consumeStart(agentId, message, token, workspace, sender) {
+    const result = workspace.consumeLink(token);
+    if (result.status === "unknown") {
+        await sender.sendText(message.chatId, "This link token is unknown or has expired. Start a new link from the web UI.");
+        return;
+    }
+    if (result.status === "expired") {
+        await sender.sendText(message.chatId, "This link token has expired. Start a new link from the web UI.");
+        return;
+    }
+    if (result.agentId !== agentId) {
+        await sender.sendText(message.chatId, "This link token belongs to a different agent.");
+        return;
+    }
+    const bound = await workspace.bindChat(agentId, message.chatId, message.fromUsername);
+    if (!bound) {
+        await sender.sendText(message.chatId, "This Telegram gateway is no longer configured. Start a new link from the web UI.");
+        return;
+    }
+    await sender.sendText(message.chatId, "Telegram chat linked. You can now use this chat with HyperVibes.");
+}
+async function handleCommand(agentId, chatId, command, workspace, sender) {
+    if (command.name === "help") {
+        await sender.sendText(chatId, HELP_TEXT);
+        return;
+    }
+    let handle;
+    try {
+        handle = await workspace.bridge(agentId);
+    }
+    catch (error) {
+        await sender.sendText(chatId, bridgeErrorText(error));
+        return;
+    }
+    try {
+        if (command.name === "stop") {
+            await handle.stop();
+            await sender.sendText(chatId, "Active turn stopped.");
+        }
+        else if (command.name === "reset") {
+            await handle.reset();
+            await sender.sendText(chatId, "Started a fresh conversation.");
+        }
+        else if (command.name === "compact") {
+            const result = await handle.compact();
+            await sender.sendText(chatId, result.message ?? "Conversation compacted.");
+        }
+        else {
+            await sender.sendText(chatId, HELP_TEXT);
+        }
+    }
+    catch (error) {
+        workspace.logger?.warn("Telegram command failed", error);
+        await sender.sendText(chatId, bridgeErrorText(error));
+    }
+}
+async function handleTelegramMessage(agentId, message, workspace, sender) {
+    const text = message.text.trim();
+    const startToken = extractStartPayload(text);
+    if (startToken) {
+        await consumeStart(agentId, message, startToken, workspace, sender);
+        return;
+    }
+    const command = parseCommand(text);
+    if (command?.name === "start") {
+        // `/start` without a payload: guide the operator toward the link flow.
+        await sender.sendText(message.chatId, "To link this chat, open your Agent's settings page and start a Telegram link.");
+        return;
+    }
+    const gateway = await workspace.loadGateway(agentId);
+    // Only the chat that completed the link flow may talk to the Agent.
+    if (!gateway || gateway.chatId === null || gateway.chatId !== message.chatId) {
+        workspace.logger?.warn(`Telegram message from unauthorized chat ${message.chatId} ignored`);
+        return;
+    }
+    if (command) {
+        await handleCommand(agentId, message.chatId, command, workspace, sender);
+        return;
+    }
+    if (text)
+        await submitChat(agentId, message.chatId, text, workspace, sender);
+}
+/** The Telegram platform: deep links, commands, and the chat authorization model. */
+export const telegramConnector = {
+    type: "telegram",
+    label: "Telegram",
+    createEndpoint: grammyEndpoint,
+    handle: handleTelegramMessage,
+    linkUrl: (row, token) => `https://t.me/${row.botUsername}?start=${token}`,
+};