@hivemagnus/ardent 0.0.0-stage → 1.0.2

package/dist/team-contract.js

@@ -0,0 +1,84 @@
+import { z } from 'zod';
+export const TEAM_VERSION = '1.0';
+export const TEAM_TASK_METADATA_KEY = 'hermesTeamTask';
+export const TEAM_CLARIFICATION_METADATA_KEY = 'hermesTeamClarification';
+/** A configured peer ID (see peers.yaml). */
+const role = z.string().regex(/^[a-z][a-z0-9_-]{0,63}$/);
+const boundedId = z.string().regex(/^[A-Za-z0-9._:-]{1,128}$/);
+const text = (bytes) => z.string().trim().min(1).refine(value => Buffer.byteLength(value, 'utf8') <= bytes, `Exceeds ${bytes} bytes`);
+const texts = (minimum = 0) => z.array(text(1000)).min(minimum).max(32).refine(value => new Set(value).size === value.length, 'Duplicate entries');
+const Action = z.enum(['observe', 'analyze', 'create_artifact', 'create_draft', 'reversible_change', 'deploy', 'external_publish', 'destructive_response']);
+/** The mission shape without its cross-field rules (Zod 4 cannot omit fields from a refined object). */
+export const TeamMissionShape = z.object({
+    id: boundedId,
+    revision: z.number().int().min(1).max(2147483647),
+    parent_task: boundedId.nullable(),
+    constraints: texts(),
+    allowed_actions: z.array(Action).min(1).max(8).refine(value => new Set(value).size === value.length, 'Duplicate action'),
+    resources: texts(1),
+    deadline: z.number().int().min(1).max(253402300799),
+    acceptance_criteria: texts(1),
+    expected_artifacts: texts()
+}).strict();
+export const TeamMission = TeamMissionShape;
+export const TeamEnvelope = z.object({ version: z.literal(TEAM_VERSION), caller: role, task_id: boundedId, objective: text(16000), mission: TeamMission }).strict();
+const Clarification = z.object({ missing_fact: text(1200), choices: z.array(z.object({ id: boundedId, label: text(300) }).strict()).max(8), blocked_task: boundedId, intended_respondent: z.union([role, z.literal('operator')]) }).strict();
+const Check = z.object({ criterion: text(1000), status: z.enum(['pass', 'fail', 'unknown']), evidence: z.array(text(1000)).max(16) }).strict();
+const Artifact = z.object({ name: text(1000), reference: text(1000), sha256: z.string().regex(/^[a-f0-9]{64}$/) }).strict();
+export const TeamResult = z.object({
+    version: z.literal(TEAM_VERSION), mission_id: boundedId, mission_revision: z.number().int().min(1), task_id: boundedId,
+    outcome: z.enum(['completed', 'partial', 'failed', 'blocked', 'input_required', 'cancelled', 'unknown']),
+    summary: text(16000), checks: z.array(Check).max(32), artifacts: z.array(Artifact).max(32), uncertain_effects: texts(),
+    clarification: Clarification.optional()
+}).strict();
+export function validateTeamEnvelope(value, authenticatedPeer, messageId, objective, nowSeconds = Date.now() / 1000, child = false) {
+    const envelope = TeamEnvelope.parse(value);
+    if (envelope.caller !== authenticatedPeer || envelope.task_id !== messageId || envelope.objective !== objective)
+        throw new Error('Team envelope does not match authenticated message');
+    if (child ? envelope.mission.parent_task === null : envelope.mission.parent_task !== null)
+        throw new Error('Child mission requires an exact retained root reservation');
+    if (envelope.mission.deadline <= nowSeconds)
+        throw new Error('Team mission deadline expired');
+    if (Buffer.byteLength(JSON.stringify(envelope), 'utf8') > 48_000)
+        throw new Error('Team envelope exceeds 48 KiB');
+    return envelope;
+}
+export function validateTeamResult(raw, envelope, knownReferences) {
+    if (Buffer.byteLength(raw, 'utf8') > 262_144)
+        throw new Error('Team result exceeds 256 KiB');
+    let text = raw.trim().replace(/^\[INPUT_REQUIRED\]\s*/, '');
+    if (text.startsWith('```json\n') && text.endsWith('\n```'))
+        text = text.slice(8, -4);
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch {
+        throw new Error('A structured JSON team result is required');
+    }
+    const result = TeamResult.parse(value);
+    if (result.mission_id !== envelope.mission.id || result.mission_revision !== envelope.mission.revision || result.task_id !== envelope.task_id)
+        throw new Error('Team result mission or task binding differs');
+    if (result.clarification && (result.outcome !== 'input_required' || result.clarification.blocked_task !== envelope.task_id))
+        throw new Error('Invalid team clarification binding');
+    const criteria = new Set(envelope.mission.acceptance_criteria);
+    const seen = new Set();
+    for (const check of result.checks) {
+        if (!criteria.has(check.criterion) || seen.has(check.criterion))
+            throw new Error('Unknown or duplicate team check');
+        if (knownReferences && check.evidence.some(reference => !knownReferences.has(reference)))
+            throw new Error('Team check cites an unobserved evidence reference');
+        seen.add(check.criterion);
+    }
+    const names = new Set();
+    for (const artifact of result.artifacts) {
+        if (names.has(artifact.name))
+            throw new Error('Duplicate team artifact');
+        names.add(artifact.name);
+    }
+    if (result.outcome === 'completed' &&
+        (seen.size !== criteria.size || result.checks.some(check => check.status !== 'pass' || !check.evidence.length) ||
+            envelope.mission.expected_artifacts.some(name => !names.has(name)) || result.uncertain_effects.length))
+        throw new Error('Team completion lacks checks, artifacts, or effect certainty');
+    return result;
+}

package/dist/team-control.d.ts

@@ -0,0 +1,8 @@
+import type { ArdentRuntime } from './runtime.js';
+/** Deterministic receiver-side lifecycle controls for an accepted team task. */
+export declare class TeamControlService {
+    #private;
+    readonly runtime: ArdentRuntime;
+    constructor(runtime: ArdentRuntime);
+    handle(raw: unknown, tenant: string, caller: string): object;
+}

package/dist/team-control.js

@@ -0,0 +1,152 @@
+import { createHash } from 'node:crypto';
+import { z } from 'zod';
+import { TeamEnvelope } from './team-contract.js';
+const id = z.string().regex(/^[A-Za-z0-9._:-]{1,128}$/);
+const EventsPayload = z.object({ native_task_id: id, after_cursor: z.number().int().min(0), limit: z.number().int().min(1).max(100) }).strict();
+const ControlPayload = z.object({ native_task_id: id, task_id: id, mission_revision: z.number().int().min(1), control_id: id, control_version: z.number().int().min(1), action: z.enum(['pause', 'resume', 'cancel']) }).strict();
+const TeamControl = z.discriminatedUnion('action', [
+    z.object({ version: z.literal('1.0'), action: z.literal('task_events'), key: id, payload: EventsPayload }).strict(),
+    z.object({ version: z.literal('1.0'), action: z.literal('task_control'), key: id, payload: ControlPayload }).strict()
+]);
+const MissionRow = z.object({ envelope_json: z.string(), tenant: z.string(), caller: z.string(), operation_id: z.string() });
+const RequestRow = z.object({ request_digest: z.string(), receipt_json: z.string() });
+const AdmissionRow = z.object({ version: z.number(), admission: z.enum(['open', 'paused', 'cancel_requested']) });
+const ControlRow = z.object({ payload_sha256: z.string(), receipt_json: z.string() });
+const EventRow = z.object({ sequence: z.number(), kind: z.string(), detail_json: z.string(), created_ms: z.number() });
+function canonical(value) {
+    const sort = (input) => {
+        if (Array.isArray(input))
+            return input.map(sort);
+        if (input && typeof input === 'object')
+            return Object.fromEntries(Object.entries(input).sort(([a], [b]) => a.localeCompare(b)).map(([key, item]) => [key, sort(item)]));
+        return input;
+    };
+    return JSON.stringify(sort(value));
+}
+function digest(value) { return createHash('sha256').update(canonical(value)).digest('hex'); }
+/** Deterministic receiver-side lifecycle controls for an accepted team task. */
+export class TeamControlService {
+    runtime;
+    constructor(runtime) {
+        this.runtime = runtime;
+        runtime.store.db.exec(`CREATE TABLE IF NOT EXISTS a2a_team_control_requests (
+      tenant TEXT NOT NULL, caller TEXT NOT NULL, request_key TEXT NOT NULL,
+      request_digest TEXT NOT NULL, receipt_json TEXT NOT NULL,
+      PRIMARY KEY(tenant,caller,request_key));
+      CREATE TABLE IF NOT EXISTS a2a_team_admission (
+        a2a_task_id TEXT PRIMARY KEY, operation_id TEXT NOT NULL, version INTEGER NOT NULL,
+        admission TEXT NOT NULL, updated_ms INTEGER NOT NULL);
+      CREATE TABLE IF NOT EXISTS a2a_team_controls (
+        a2a_task_id TEXT NOT NULL, control_id TEXT NOT NULL, payload_sha256 TEXT NOT NULL,
+        receipt_json TEXT NOT NULL, PRIMARY KEY(a2a_task_id,control_id));
+      CREATE TABLE IF NOT EXISTS a2a_operation_links (
+        a2a_task_id TEXT NOT NULL, operation_id TEXT NOT NULL,
+        PRIMARY KEY(a2a_task_id,operation_id));`);
+    }
+    #mission(taskId, tenant, caller) {
+        const row = this.runtime.store.db.prepare(`SELECT m.envelope_json,m.tenant,m.caller,o.operation_id FROM a2a_team_missions m
+      JOIN a2a_operation_map o ON o.a2a_task_id=m.a2a_task_id
+      JOIN a2a_tasks t ON t.id=m.a2a_task_id
+      WHERE m.a2a_task_id=? AND t.tenant=? AND t.caller=?`).get(taskId, tenant, caller);
+        if (!row)
+            throw new Error('Accepted team task is unavailable to this peer');
+        const bound = MissionRow.parse(row);
+        if (bound.tenant !== tenant || bound.caller !== caller)
+            throw new Error('Team task owner differs');
+        const raw = JSON.parse(bound.envelope_json);
+        return { envelope: TeamEnvelope.parse(raw), operationId: bound.operation_id };
+    }
+    #events(payload, tenant, caller) {
+        const { envelope } = this.#mission(payload.native_task_id, tenant, caller);
+        const rows = this.runtime.store.db.prepare(`SELECT e.sequence,e.kind,e.detail_json,e.created_ms FROM events e
+      JOIN a2a_operation_links l ON l.operation_id=e.task_id
+      WHERE l.a2a_task_id=? AND e.sequence>? ORDER BY e.sequence LIMIT ?`).all(payload.native_task_id, payload.after_cursor, payload.limit + 1)
+            .map(row => EventRow.parse(row));
+        const events = [];
+        let bytes = 0;
+        for (const row of rows.slice(0, payload.limit)) {
+            const detail = JSON.parse(row.detail_json);
+            let item = { cursor: row.sequence, task_id: payload.native_task_id, kind: row.kind,
+                stage: row.kind.startsWith('tool_') ? 'tool' : row.kind.startsWith('model_') ? 'model' : 'task',
+                status: 'observed', summary: row.kind.replaceAll('_', ' ').slice(0, 160), data: detail,
+                created: row.created_ms / 1000 };
+            if (Buffer.byteLength(canonical(item)) > 32_768)
+                item = { ...item, data: { truncated: true } };
+            const size = Buffer.byteLength(canonical(item));
+            if (events.length && bytes + size > 32_768)
+                break;
+            events.push(item);
+            bytes += size;
+        }
+        const last = events.at(-1);
+        const nextCursor = last?.cursor ?? payload.after_cursor;
+        return { native_task_id: payload.native_task_id, task_id: envelope.task_id, events,
+            next_cursor: nextCursor, has_more: rows.some(row => row.sequence > nextCursor) };
+    }
+    #control(payload, tenant, caller) {
+        const { envelope, operationId } = this.#mission(payload.native_task_id, tenant, caller);
+        if (envelope.task_id !== payload.task_id || envelope.mission.revision !== payload.mission_revision)
+            throw new Error('Team control task or mission revision differs');
+        const db = this.runtime.store.db;
+        return db.transaction(() => {
+            const priorRaw = db.prepare('SELECT payload_sha256,receipt_json FROM a2a_team_controls WHERE a2a_task_id=? AND control_id=?')
+                .get(payload.native_task_id, payload.control_id);
+            const fingerprint = digest(payload);
+            if (priorRaw) {
+                const prior = ControlRow.parse(priorRaw);
+                if (prior.payload_sha256 !== fingerprint)
+                    throw new Error('Team control ID reused with different content');
+                const data = JSON.parse(prior.receipt_json);
+                return { data: z.record(z.string(), z.unknown()).parse(data), ...(payload.action === 'cancel' ? { cancelOperation: operationId } : {}) };
+            }
+            const currentRaw = db.prepare('SELECT version,admission FROM a2a_team_admission WHERE a2a_task_id=?').get(payload.native_task_id);
+            const current = currentRaw ? AdmissionRow.parse(currentRaw) : { version: 0, admission: 'open' };
+            if (payload.control_version <= current.version)
+                throw new Error('Stale team control version');
+            if (current.admission === 'cancel_requested' && payload.action !== 'cancel')
+                throw new Error('Cancellation admission cannot be reopened');
+            if (payload.action === 'resume' && envelope.mission.deadline <= Date.now() / 1000)
+                throw new Error('Expired team mission cannot resume');
+            const admission = payload.action === 'pause' ? 'paused' : payload.action === 'resume' ? 'open' : 'cancel_requested';
+            db.prepare(`INSERT INTO a2a_team_admission(a2a_task_id,operation_id,version,admission,updated_ms) VALUES (?,?,?,?,?)
+        ON CONFLICT(a2a_task_id) DO UPDATE SET operation_id=excluded.operation_id,version=excluded.version,admission=excluded.admission,updated_ms=excluded.updated_ms`)
+                .run(payload.native_task_id, operationId, payload.control_version, admission, Date.now());
+            const data = { control_id: payload.control_id, native_task_id: payload.native_task_id,
+                control_version: payload.control_version, admission, execution_stopped: false,
+                provider_work_stopped: false, undo: false, delivery: 'acknowledged' };
+            db.prepare('INSERT INTO a2a_team_controls(a2a_task_id,control_id,payload_sha256,receipt_json) VALUES (?,?,?,?)')
+                .run(payload.native_task_id, payload.control_id, fingerprint, canonical(data));
+            this.runtime.store.append(operationId, 'team_control', data);
+            return { data, ...(payload.action === 'cancel' ? { cancelOperation: operationId } : {}) };
+        })();
+    }
+    handle(raw, tenant, caller) {
+        const control = TeamControl.parse(raw);
+        const requestDigest = digest(control);
+        const db = this.runtime.store.db;
+        const priorRaw = db.prepare('SELECT request_digest,receipt_json FROM a2a_team_control_requests WHERE tenant=? AND caller=? AND request_key=?')
+            .get(tenant, caller, control.key);
+        if (priorRaw) {
+            const prior = RequestRow.parse(priorRaw);
+            if (prior.request_digest !== requestDigest)
+                throw new Error('Team control key reused with different content');
+            const stored = JSON.parse(prior.receipt_json);
+            // A crash between persisting a cancel receipt and signaling the local
+            // operation must not make a retried request a no-op.
+            if (control.action === 'task_control' && control.payload.action === 'cancel') {
+                const { operationId } = this.#mission(control.payload.native_task_id, tenant, caller);
+                this.runtime.cancel(operationId);
+            }
+            return z.record(z.string(), z.unknown()).parse(stored);
+        }
+        const result = control.action === 'task_events'
+            ? { data: this.#events(control.payload, tenant, caller) }
+            : this.#control(control.payload, tenant, caller);
+        const receipt = { version: '1.0', request_digest: requestDigest, data: result.data };
+        db.prepare('INSERT INTO a2a_team_control_requests(tenant,caller,request_key,request_digest,receipt_json) VALUES (?,?,?,?,?)')
+            .run(tenant, caller, control.key, requestDigest, canonical(receipt));
+        if (result.cancelOperation)
+            this.runtime.cancel(result.cancelOperation);
+        return receipt;
+    }
+}

package/dist/telegram.d.ts

@@ -0,0 +1,35 @@
+import type { ArdentRuntime } from './runtime.js';
+import type { JobEngine } from './job-engine.js';
+type TelegramConfig = ArdentRuntime['config']['channels']['telegram'];
+export declare class TelegramConflictError extends Error {
+}
+export declare class TelegramAdapter {
+    #private;
+    readonly runtime: ArdentRuntime;
+    readonly config: TelegramConfig;
+    constructor(runtime: ArdentRuntime, config: TelegramConfig, env?: NodeJS.ProcessEnv, baseUrl?: string, jobs?: JobEngine);
+    initialize(signal?: AbortSignal): Promise<{
+        botId: number;
+        username: string | null;
+    }>;
+    /**
+     * Send one notice to an allowlisted private chat (for plugins and jobs).
+     * With `parseMode`, Telegram returns rendered text, so the receipt binds the
+     * submitted digest and provider message ID instead of the echoed text.
+     */
+    sendNotice(chatId: number, body: string, signal?: AbortSignal, parseMode?: 'MarkdownV2' | 'HTML'): Promise<{
+        message_id: string;
+        chat_id: number;
+        chat_type: 'private';
+        body_sha256: string;
+    }>;
+    /** `signal` stops intake; `deliverySignal` aborts replies already admitted from this poll. */
+    pollOnce(signal?: AbortSignal, deliverySignal?: AbortSignal | undefined): Promise<number>;
+    drain(): Promise<void>;
+    /**
+     * Polls until `signal` aborts, then waits for admitted updates. Their replies
+     * use `deliverySignal`, so a shutdown can stop intake before cutting delivery.
+     */
+    run(signal: AbortSignal, deliverySignal?: AbortSignal): Promise<void>;
+}
+export {};

package/dist/telegram.js

@@ -0,0 +1,284 @@
+import { createHash } from 'node:crypto';
+import { setTimeout as sleep } from 'node:timers/promises';
+import { z } from 'zod';
+import { ChannelCore, DeliveryRejectedError } from './channels.js';
+const User = z.object({ id: z.number().int(), is_bot: z.boolean().default(false), username: z.string().optional() }).passthrough();
+const Document = z.object({ file_id: z.string(), file_name: z.string().default('attachment'), mime_type: z.string().default('application/octet-stream'), file_size: z.number().int().nonnegative().optional() }).passthrough();
+const Message = z.object({ message_id: z.number().int(), from: User.optional(), chat: z.object({ id: z.number().int(), type: z.string() }).passthrough(), text: z.string().optional(), caption: z.string().optional(), message_thread_id: z.number().int().optional(), reply_to_message: z.object({ message_id: z.number().int() }).passthrough().optional(), document: Document.optional() }).passthrough();
+const Update = z.object({ update_id: z.number().int(), message: Message.optional() }).passthrough();
+const Envelope = z.object({ ok: z.boolean(), result: z.unknown().optional(), error_code: z.number().int().optional(), description: z.string().optional(), parameters: z.object({ retry_after: z.number().int().positive().optional() }).passthrough().optional() }).passthrough();
+export class TelegramConflictError extends Error {
+}
+function splitText(value) {
+    const parts = [];
+    let rest = value || '(empty response)';
+    while (rest.length) {
+        if (rest.length <= 3900) {
+            parts.push(rest);
+            break;
+        }
+        let index = rest.lastIndexOf('\n', 3900);
+        if (index < 2000)
+            index = rest.lastIndexOf(' ', 3900);
+        if (index < 2000)
+            index = 3900;
+        if (index > 0 && /[\uD800-\uDBFF]/.test(rest[index - 1] ?? '') && /[\uDC00-\uDFFF]/.test(rest[index] ?? ''))
+            index--;
+        parts.push(rest.slice(0, index));
+        rest = rest.slice(index).trimStart();
+    }
+    return parts;
+}
+export class TelegramAdapter {
+    runtime;
+    config;
+    #core;
+    #pending = new Set();
+    #commitQueue = [];
+    #token;
+    #base;
+    #bot;
+    #consumerConflict = false;
+    #nextOffset;
+    constructor(runtime, config, env = process.env, baseUrl = 'https://api.telegram.org', jobs) {
+        this.runtime = runtime;
+        this.config = config;
+        const token = env[config.token_env];
+        if (!token || !/^\d+:[A-Za-z0-9_-]{20,}$/.test(token))
+            throw new Error('Telegram token is missing or malformed');
+        if (config.allowed_user_ids.length === 0)
+            throw new Error('Telegram requires at least one allowed user');
+        this.#token = token;
+        this.#base = baseUrl.replace(/\/$/, '');
+        this.#core = new ChannelCore(runtime, env, jobs);
+    }
+    async #call(method, body, signal) {
+        for (let attempt = 0; attempt < 4; attempt++) {
+            const response = await fetch(`${this.#base}/bot${this.#token}/${method}`, {
+                method: 'POST',
+                ...(body instanceof FormData ? {} : { headers: { 'Content-Type': 'application/json' } }),
+                body: body instanceof FormData ? body : JSON.stringify(body),
+                ...(signal ? { signal } : {}),
+                redirect: 'error'
+            });
+            const parsed = Envelope.parse(await response.json());
+            if (response.status === 409 || parsed.error_code === 409) {
+                this.#consumerConflict = true;
+                throw new TelegramConflictError(`Telegram consumer conflict: ${parsed.description ?? 'another poller or webhook owns the bot'}`);
+            }
+            if (response.status === 429 && parsed.parameters?.retry_after && attempt < 3) {
+                // The abortable timer removes its listener, so a long-lived signal does not accumulate them.
+                await sleep(Math.min(parsed.parameters?.retry_after ?? 1, 60) * 1000, undefined, signal ? { signal } : {})
+                    .catch(() => { throw new Error('Telegram retry aborted'); });
+                continue;
+            }
+            if (!response.ok || !parsed.ok) {
+                const message = `Telegram ${method} failed: ${parsed.description ?? response.status}`;
+                if (response.status >= 400 && response.status < 500)
+                    throw new DeliveryRejectedError(message);
+                throw new Error(message);
+            }
+            return parsed.result;
+        }
+        throw new Error(`Telegram ${method} retry limit reached`);
+    }
+    async initialize(signal) {
+        const me = User.parse(await this.#call('getMe', {}, signal));
+        if (!me.is_bot)
+            throw new Error('Telegram token does not identify a bot');
+        const webhook = z.object({ url: z.string() }).passthrough().parse(await this.#call('getWebhookInfo', {}, signal));
+        if (webhook.url)
+            throw new TelegramConflictError('Telegram webhook is configured; polling cannot start until explicit handover');
+        this.#bot = me;
+        return { botId: me.id, username: me.username ?? null };
+    }
+    /**
+     * Send one notice to an allowlisted private chat (for plugins and jobs).
+     * With `parseMode`, Telegram returns rendered text, so the receipt binds the
+     * submitted digest and provider message ID instead of the echoed text.
+     */
+    async sendNotice(chatId, body, signal, parseMode) {
+        if (this.runtime.store.admissionFence())
+            throw new Error('Profile admission is fenced for rollback');
+        if (!Number.isSafeInteger(chatId) || chatId <= 0 || !this.config.allowed_user_ids.includes(chatId))
+            throw new Error('Notice chat is outside the Telegram allowlist');
+        if (!body.trim() || Buffer.byteLength(body, 'utf16le') / 2 > 3900)
+            throw new Error('Notice exceeds one Telegram message');
+        const message = Message.parse(await this.#call('sendMessage', { chat_id: chatId, text: body,
+            ...(parseMode ? { parse_mode: parseMode } : {}), disable_web_page_preview: true }, signal));
+        if (message.chat.id !== chatId || message.chat.type !== 'private' || message.message_id <= 0 ||
+            (!parseMode && message.text !== body))
+            throw new Error('Telegram notice receipt differs from bound recipient or submitted body');
+        return { message_id: String(message.message_id), chat_id: chatId, chat_type: 'private',
+            body_sha256: createHash('sha256').update(body).digest('hex') };
+    }
+    /** `signal` stops intake; `deliverySignal` aborts replies already admitted from this poll. */
+    async pollOnce(signal, deliverySignal = signal) {
+        if (this.runtime.store.admissionFence())
+            throw new Error('Profile admission is fenced for rollback');
+        if (this.#consumerConflict)
+            throw new TelegramConflictError('Telegram polling is disabled after a consumer conflict');
+        if (!this.#bot)
+            await this.initialize(signal);
+        const account = String(this.#bot?.id);
+        const cursorKey = `telegram:${account}:offset`;
+        this.#nextOffset ??= Number(this.runtime.store.cursor(cursorKey) ?? '0');
+        const offset = this.#nextOffset;
+        const raw = await this.#call('getUpdates', { offset, timeout: 25, limit: 50, allowed_updates: ['message'] }, signal);
+        const updates = z.array(Update).max(50).parse(raw).filter(update => update.update_id >= offset).sort((a, b) => a.update_id - b.update_id);
+        for (const update of updates) {
+            const next = update.update_id + 1;
+            const entry = { next, accepted: false, done: false };
+            this.#commitQueue.push(entry);
+            let readyResolve = () => { };
+            let readyReject = () => { };
+            const ready = new Promise((resolve, reject) => { readyResolve = () => { entry.accepted = true; resolve(); }; readyReject = reject; });
+            const operation = this.#handleUpdate(update, readyResolve, deliverySignal).catch(error => {
+                readyReject(error);
+                this.runtime.store.setCursor(`telegram:${account}:last_error`, error instanceof Error ? error.message.slice(0, 500) : 'unknown');
+            }).finally(() => {
+                if (!entry.accepted) {
+                    const index = this.#commitQueue.indexOf(entry);
+                    if (index >= 0)
+                        this.#commitQueue.splice(index, 1);
+                    return;
+                }
+                entry.done = true;
+                while (this.#commitQueue[0]?.done) {
+                    const completed = this.#commitQueue.shift();
+                    if (completed)
+                        this.runtime.store.setCursor(cursorKey, String(completed.next));
+                }
+            });
+            this.#pending.add(operation);
+            void operation.finally(() => this.#pending.delete(operation));
+            await ready;
+            this.#nextOffset = next;
+        }
+        return updates.length;
+    }
+    async drain() { await Promise.allSettled([...this.#pending]); }
+    /**
+     * Polls until `signal` aborts, then waits for admitted updates. Their replies
+     * use `deliverySignal`, so a shutdown can stop intake before cutting delivery.
+     */
+    async run(signal, deliverySignal = signal) {
+        await this.initialize(signal);
+        let failures = 0;
+        while (!signal.aborted) {
+            try {
+                await this.pollOnce(signal, deliverySignal);
+                failures = 0;
+            }
+            catch (error) {
+                if (signal.aborted)
+                    break;
+                if (error instanceof TelegramConflictError)
+                    throw error;
+                failures++;
+                // Abort-aware so shutdown does not wait out the reconnect backoff.
+                await sleep(Math.min(30_000, 1000 * 2 ** Math.min(failures, 5)), undefined, { signal }).catch(() => { });
+            }
+        }
+        await this.drain();
+    }
+    async #handleUpdate(update, ready, signal) {
+        const message = update.message;
+        if (!message?.from || message.from.is_bot || message.from.id === this.#bot?.id) {
+            ready();
+            return;
+        }
+        if (!this.config.allowed_user_ids.includes(message.from.id)) {
+            ready();
+            return;
+        }
+        if (message.chat.type !== 'private' && !this.config.allowed_chat_ids.includes(message.chat.id)) {
+            ready();
+            return;
+        }
+        if (!['private', 'group', 'supergroup'].includes(message.chat.type)) {
+            ready();
+            return;
+        }
+        const text = message.text ?? message.caption ?? '';
+        if (message.chat.type !== 'private') {
+            const username = this.#bot?.username;
+            if (!username) {
+                ready();
+                return;
+            }
+            if (!new RegExp(`(^|\\s)@${username}(?=\\s|$)`, 'i').test(text) && !new RegExp(`^/\\w+@${username}(?=\\s|$)`, 'i').test(text)) {
+                ready();
+                return;
+            }
+        }
+        const cleanText = this.#bot?.username ? text.replace(new RegExp(`(^|\\s)@${this.#bot.username}(?=\\s|$)`, 'gi'), '$1').replace(new RegExp(`^(/\\w+)@${this.#bot.username}(?=\\s|$)`, 'i'), '$1').trim() : text;
+        const attachments = [];
+        if (message.document) {
+            const doc = message.document;
+            const attachment = { name: doc.file_name.slice(0, 128), media_type: doc.mime_type.slice(0, 100), external_id: doc.file_id.slice(0, 256) };
+            if ((doc.file_size ?? Number.POSITIVE_INFINITY) <= 2 * 1024 * 1024 && ['text/plain', 'text/markdown', 'application/json'].includes(doc.mime_type)) {
+                const file = z.object({ file_path: z.string() }).passthrough().parse(await this.#call('getFile', { file_id: doc.file_id }, signal));
+                if (/^[A-Za-z0-9_./-]{1,512}$/.test(file.file_path) && !file.file_path.split('/').includes('..')) {
+                    const response = await fetch(`${this.#base}/file/bot${this.#token}/${file.file_path}`, { ...(signal ? { signal } : {}), redirect: 'error' });
+                    if (response.ok) {
+                        const bytes = new Uint8Array(await response.arrayBuffer());
+                        if (bytes.length <= 2 * 1024 * 1024)
+                            attachment.bytes = bytes;
+                    }
+                }
+            }
+            attachments.push(attachment);
+        }
+        const event = { platform: 'telegram',
+            channel_type: message.chat.type === 'private' ? 'telegram_private'
+                : message.chat.type === 'group' ? 'telegram_group' : 'telegram_supergroup',
+            account: String(this.#bot?.id), user: String(message.from.id), conversation: String(message.chat.id), thread: message.message_thread_id === undefined ? null : String(message.message_thread_id), update_id: String(update.update_id), reply_to: String(message.message_id), text: cleanText, attachments, authorized: true, bot_message: false };
+        const typingBody = { chat_id: message.chat.id, action: 'typing', ...(message.message_thread_id === undefined ? {} : { message_thread_id: message.message_thread_id }) };
+        let typingInFlight = null;
+        const showTyping = () => {
+            if (!typingInFlight) {
+                const requestSignal = signal ? AbortSignal.any([signal, AbortSignal.timeout(2500)]) : AbortSignal.timeout(2500);
+                typingInFlight = this.#call('sendChatAction', typingBody, requestSignal).then(() => { }, () => { }).finally(() => { typingInFlight = null; });
+            }
+            return typingInFlight;
+        };
+        const initialTyping = showTyping();
+        const typing = setInterval(() => { void showTyping(); }, 4000);
+        try {
+            const operation = this.#core.handle(event, async (reply) => { await initialTyping; return this.#deliver(message, reply, signal); });
+            ready();
+            await operation;
+        }
+        finally {
+            clearInterval(typing);
+        }
+    }
+    async #deliver(message, reply, signal) {
+        const common = { chat_id: message.chat.id, reply_parameters: { message_id: message.message_id }, ...(message.message_thread_id === undefined ? {} : { message_thread_id: message.message_thread_id }) };
+        let last = null;
+        try {
+            for (const part of splitText(reply.text)) {
+                const response = Message.parse(await this.#call('sendMessage', { ...common, text: part }, signal));
+                last = String(response.message_id);
+            }
+            for (const [index, id] of reply.artifactIds.slice(0, 2).entries()) {
+                const bytes = await this.runtime.artifacts.get(id);
+                const form = new FormData();
+                form.set('chat_id', String(message.chat.id));
+                form.set('reply_parameters', JSON.stringify({ message_id: message.message_id }));
+                if (message.message_thread_id !== undefined)
+                    form.set('message_thread_id', String(message.message_thread_id));
+                form.set('document', new Blob([new Uint8Array(bytes)], { type: 'application/octet-stream' }), index === 0 ? 'research-brief.json' : 'research-brief.md');
+                const response = Message.parse(await this.#call('sendDocument', form, signal));
+                last = String(response.message_id);
+            }
+        }
+        catch (error) {
+            if (last)
+                throw new Error(`Telegram delivery may be partial: ${error instanceof Error ? error.message : 'unknown error'}`);
+            throw error;
+        }
+        return last;
+    }
+}

package/dist/tools.d.ts

@@ -0,0 +1,48 @@
+import { z } from 'zod';
+export type ToolContext = 'direct' | 'peer' | 'scheduled';
+export type ToolEffect = 'read' | 'artifact-write' | 'memory-write' | 'external-write';
+/** Constructed only by first-party code after proving that an effect did not open. */
+export declare class ProvenNoEffectError extends Error {
+    readonly code: string;
+    constructor(message: string, code: string);
+}
+export declare const ToolResultSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    ok: z.ZodLiteral<true>;
+    value: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$strict>, z.ZodObject<{
+    ok: z.ZodLiteral<false>;
+    code: z.ZodString;
+    message: z.ZodString;
+    effect: z.ZodEnum<{
+        none: "none";
+        unknown: "unknown";
+    }>;
+}, z.core.$strict>], "ok">;
+export type ToolResult = z.infer<typeof ToolResultSchema>;
+export interface Tool {
+    name: string;
+    description: string;
+    input: z.ZodType<unknown>;
+    output: z.ZodType<unknown>;
+    effect: ToolEffect;
+    contexts: readonly ToolContext[];
+    timeoutMs: number;
+    invoke(input: unknown, signal: AbortSignal): Promise<unknown>;
+}
+export declare function defineTool<I extends z.ZodTypeAny, O extends z.ZodTypeAny>(definition: {
+    name: string;
+    description: string;
+    input: I;
+    output: O;
+    effect: ToolEffect;
+    contexts: readonly ToolContext[];
+    timeoutMs: number;
+    handler: (input: z.infer<I>, signal: AbortSignal) => Promise<z.infer<O>>;
+}): Tool;
+export declare class ToolRegistry {
+    #private;
+    register(tool: Tool): void;
+    list(context: ToolContext): Tool[];
+    schemas(context: ToolContext): object[];
+    call(name: string, args: unknown, context: ToolContext, signal: AbortSignal): Promise<ToolResult>;
+}