@hirey/hi-agent-delivery 0.1.3

package/README.md

@@ -0,0 +1,17 @@
+# hi-agent-delivery
+
+`hi-agent-delivery` 承载 Hi external agent control plane 的持久化层。
+
+## 职责
+
+- `agent_event_outbox`
+- 事务、查询、事件 envelope 映射
+- outbox claim / ack / replay / idempotency
+- 供 `hi-platform` / `hi-agent-gateway` 复用的最薄数据库原语
+
+## 非职责
+
+- 不再承载旧的 `registered_agents` / `agent_delivery_endpoints` 兼容服务
+- 不暴露公网 HTTP / registry / delivery profile 编排逻辑
+
+这个仓不暴露公网 HTTP；它是 `hi-agent-gateway` 与 `hi-platform` 共同依赖的持久化实现层。

package/dist/config.d.ts

@@ -0,0 +1,6 @@
+export declare const CONFIG: {
+    DATABASE_URL: string;
+    DB_POOL_MAX: number;
+};
+export declare function validateRuntimeConfig(): void;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAOA,eAAO,MAAM,MAAM;;;CAGlB,CAAC;AAEF,wBAAgB,qBAAqB,SAIpC"}

package/dist/config.js

@@ -0,0 +1,14 @@
+// hi-agent-delivery 只关心持久化层需要的数据库参数。
+function readIntEnv(name, fallback) {
+    const value = Number(process.env[name] || fallback);
+    return Number.isFinite(value) && value > 0 ? Math.floor(value) : fallback;
+}
+export const CONFIG = {
+    DATABASE_URL: String(process.env.DATABASE_URL || '').trim(),
+    DB_POOL_MAX: readIntEnv('DB_POOL_MAX', 10),
+};
+export function validateRuntimeConfig() {
+    if (!CONFIG.DATABASE_URL) {
+        throw new Error('[hi-agent-delivery] DATABASE_URL is required');
+    }
+}

package/dist/db/pg.d.ts

@@ -0,0 +1,5 @@
+import { Pool, type PoolClient, type QueryResult, type QueryResultRow } from 'pg';
+export declare const pgPool: Pool;
+export declare function withTransaction<T>(fn: (client: PoolClient) => Promise<T>): Promise<T>;
+export declare function query<T extends QueryResultRow = QueryResultRow>(text: string, params?: unknown[], client?: PoolClient): Promise<QueryResult<T>>;
+//# sourceMappingURL=pg.d.ts.map

package/dist/db/pg.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pg.d.ts","sourceRoot":"","sources":["../../src/db/pg.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,KAAK,UAAU,EAAE,KAAK,WAAW,EAAE,KAAK,cAAc,EAAE,MAAM,IAAI,CAAC;AAWlF,eAAO,MAAM,MAAM,MAKjB,CAAC;AAGH,wBAAsB,eAAe,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,MAAM,EAAE,UAAU,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAe3F;AAED,wBAAsB,KAAK,CAAC,CAAC,SAAS,cAAc,GAAG,cAAc,EACnE,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,OAAO,EAAE,EAClB,MAAM,CAAC,EAAE,UAAU,GAClB,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAGzB"}

package/dist/db/pg.js

@@ -0,0 +1,37 @@
+import { Pool } from 'pg';
+import { CONFIG, validateRuntimeConfig } from '../config.js';
+validateRuntimeConfig();
+const sslMode = String(process.env.DB_SSL_MODE || '').toLowerCase();
+const sslEnabled = /^(1|true|yes|on|require|verify-ca)$/i.test(sslMode);
+const rejectUnauthorized = !/^(0|false|no|off|insecure)$/i.test(String(process.env.DB_SSL_REJECT_UNAUTHORIZED || ''));
+const ca = String(process.env.DB_SSL_CA || '').trim();
+export const pgPool = new Pool({
+    connectionString: CONFIG.DATABASE_URL,
+    max: CONFIG.DB_POOL_MAX,
+    idleTimeoutMillis: 30_000,
+    ssl: sslEnabled ? { rejectUnauthorized, ...(ca ? { ca } : {}) } : false,
+});
+// 统一事务入口，避免 outbox/ack/registry 逻辑各自拼 BEGIN/ROLLBACK。
+export async function withTransaction(fn) {
+    const client = await pgPool.connect();
+    try {
+        await client.query('BEGIN');
+        const result = await fn(client);
+        await client.query('COMMIT');
+        return result;
+    }
+    catch (error) {
+        try {
+            await client.query('ROLLBACK');
+        }
+        catch { }
+        throw error;
+    }
+    finally {
+        client.release();
+    }
+}
+export async function query(text, params, client) {
+    const runner = client || pgPool;
+    return runner.query(text, params);
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from './services/agentGatewayEvents.js';
+export * from './db/pg.js';
+export * from './payloads.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,kCAAkC,CAAC;AACjD,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export * from './services/agentGatewayEvents.js';
+export * from './db/pg.js';
+export * from './payloads.js';

package/dist/payloads.d.ts

@@ -0,0 +1,44 @@
+import type { OpenClawHooksAgentEndpointConfig, OpenResponsesEndpointConfig } from '@hirey/hi-agent-contracts';
+export type SharedAgentDeliveryEventEnvelope = {
+    event_id: string;
+    target_agent_id: string;
+    topic: string;
+    preview?: Record<string, unknown> | null;
+    payload?: Record<string, unknown> | null;
+    resource_ref?: Record<string, unknown> | null;
+};
+export declare function buildGenericEventWebhookPayload(event: SharedAgentDeliveryEventEnvelope): {
+    profile: string;
+    event: SharedAgentDeliveryEventEnvelope;
+    delivery: {
+        mode: string;
+        delivered_at: string;
+    };
+};
+export declare function buildOpenClawHookPayload(args: {
+    event: SharedAgentDeliveryEventEnvelope;
+    config?: OpenClawHooksAgentEndpointConfig | Record<string, unknown> | null;
+}): {
+    message: string;
+    name: string;
+    agentId: string | undefined;
+    sessionKey: string;
+    wakeMode: string;
+    deliver: boolean;
+    channel: string | undefined;
+    to: string | undefined;
+    model: string | undefined;
+    thinking: string | undefined;
+    timeoutSeconds: number | undefined;
+};
+export declare function buildOpenResponsesPayload(args: {
+    event: SharedAgentDeliveryEventEnvelope;
+    config: OpenResponsesEndpointConfig | Record<string, unknown>;
+}): {
+    model: string;
+    input: string;
+    instructions: string | undefined;
+    user: string;
+    stream: boolean;
+};
+//# sourceMappingURL=payloads.d.ts.map

package/dist/payloads.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"payloads.d.ts","sourceRoot":"","sources":["../src/payloads.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,gCAAgC,EAChC,2BAA2B,EAC5B,MAAM,2BAA2B,CAAC;AAGnC,MAAM,MAAM,gCAAgC,GAAG;IAC7C,QAAQ,EAAE,MAAM,CAAC;IACjB,eAAe,EAAE,MAAM,CAAC;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IACzC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IACzC,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;CAC/C,CAAC;AAWF,wBAAgB,+BAA+B,CAAC,KAAK,EAAE,gCAAgC;;;;;;;EAUtF;AAED,wBAAgB,wBAAwB,CAAC,IAAI,EAAE;IAC7C,KAAK,EAAE,gCAAgC,CAAC;IACxC,MAAM,CAAC,EAAE,gCAAgC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;CAC5E;;;;;;;;;;;;EAmBA;AAED,wBAAgB,yBAAyB,CAAC,IAAI,EAAE;IAC9C,KAAK,EAAE,gCAAgC,CAAC;IACxC,MAAM,EAAE,2BAA2B,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/D;;;;;;EAiBA"}

package/dist/payloads.js

@@ -0,0 +1,60 @@
+import { normalizeText } from '@hirey/hi-agent-contracts';
+function stringifyEventSummary(event) {
+    if (event.preview?.text)
+        return String(event.preview.text);
+    return JSON.stringify({
+        topic: event.topic,
+        payload: event.payload || {},
+        resource_ref: event.resource_ref || {},
+    });
+}
+export function buildGenericEventWebhookPayload(event) {
+    // generic webhook 始终直接转发 canonical event envelope，不额外塞宿主私货。
+    return {
+        profile: 'generic.event-webhook.v1',
+        event,
+        delivery: {
+            mode: 'accepted_is_terminal',
+            delivered_at: new Date().toISOString(),
+        },
+    };
+}
+export function buildOpenClawHookPayload(args) {
+    const config = (args.config || {});
+    const sessionKeyPrefix = normalizeText(config.session_key_prefix) || 'hi';
+    const messagePrefix = normalizeText(config.message_prefix);
+    const eventSummary = stringifyEventSummary(args.event);
+    const message = [messagePrefix, eventSummary].filter(Boolean).join('\n\n') || eventSummary;
+    return {
+        message,
+        name: normalizeText(config.name) || 'Hi',
+        agentId: normalizeText(config.agent_id) || undefined,
+        sessionKey: `${sessionKeyPrefix}:${args.event.event_id}`,
+        wakeMode: normalizeText(config.wake_mode) || 'now',
+        deliver: config.deliver !== false,
+        channel: normalizeText(config.channel) || undefined,
+        to: normalizeText(config.to) || undefined,
+        model: normalizeText(config.model) || undefined,
+        thinking: normalizeText(config.thinking) || undefined,
+        timeoutSeconds: Number(config.timeout_seconds || 0) || undefined,
+    };
+}
+export function buildOpenResponsesPayload(args) {
+    const config = args.config;
+    const model = normalizeText(config.model);
+    if (!model)
+        throw new Error('missing_openresponses_model');
+    return {
+        model,
+        input: JSON.stringify({
+            topic: args.event.topic,
+            event_id: args.event.event_id,
+            payload: args.event.payload || null,
+            resource_ref: args.event.resource_ref || null,
+            preview: args.event.preview || null,
+        }),
+        instructions: normalizeText(config.instructions) || undefined,
+        user: normalizeText(config.user) || `hi:${args.event.target_agent_id}`,
+        stream: false,
+    };
+}

package/dist/services/agentGatewayEvents.d.ts

@@ -0,0 +1,105 @@
+import type { PoolClient } from 'pg';
+import { type AgentGatewayEventPreview, type AgentGatewayResourceRef, type AgentGatewayTopic } from '@hirey/hi-agent-contracts';
+export type AgentGatewayEventEnvelope = {
+    event_id: string;
+    target_agent_id: string;
+    stream_seq: number;
+    topic: AgentGatewayTopic;
+    event_type: AgentGatewayTopic;
+    occurred_at: string | null;
+    resource_ref: AgentGatewayResourceRef;
+    preview: AgentGatewayEventPreview | null;
+    fetch_uri: string;
+    idempotency_key: string | null;
+};
+export type AgentGatewayEventSnapshot = AgentGatewayEventEnvelope & {
+    status: 'queued' | 'processing' | 'consumed' | 'failed';
+    attempts: number;
+    available_at: string | null;
+    processing_started_at: string | null;
+    claimed_by_agent_id: string | null;
+    claimed_by_lease_id: string | null;
+    claimed_at: string | null;
+    consumed_at: string | null;
+    last_error: string | null;
+    result: Record<string, unknown> | null;
+    payload: Record<string, unknown> | null;
+    created_at: string | null;
+    updated_at: string | null;
+};
+export type CreateAgentGatewayEventInput = {
+    target_agent_id: string;
+    topic?: AgentGatewayTopic | string;
+    event_type?: AgentGatewayTopic | string;
+    occurred_at?: string | null;
+    resource_ref: AgentGatewayResourceRef | Record<string, unknown>;
+    preview?: AgentGatewayEventPreview | Record<string, unknown> | null;
+    payload: Record<string, unknown>;
+    idempotency_key?: string | null;
+    status?: string | null;
+    client?: PoolClient;
+};
+export declare function createAgentGatewayEvent(input: CreateAgentGatewayEventInput): Promise<{
+    ok: true;
+    duplicate: boolean;
+    event: AgentGatewayEventSnapshot;
+}>;
+export declare function listAgentGatewayEventEnvelopes(input: {
+    agent_id: string;
+    after_seq?: number | string | null;
+    limit?: number | string | null;
+    client?: PoolClient;
+}): Promise<{
+    ok: true;
+    items: {
+        event_id: string;
+        target_agent_id: string;
+        stream_seq: number;
+        topic: AgentGatewayTopic;
+        event_type: AgentGatewayTopic;
+        occurred_at: string | null;
+        resource_ref: AgentGatewayResourceRef;
+        preview: AgentGatewayEventPreview | null;
+        fetch_uri: string;
+        idempotency_key: string | null;
+    }[];
+}>;
+export declare function getAgentGatewayEventById(input: {
+    agent_id: string;
+    event_id: string;
+    client?: PoolClient;
+}): Promise<{
+    ok: false;
+    error: string;
+    event?: undefined;
+} | {
+    ok: true;
+    event: AgentGatewayEventSnapshot;
+    error?: undefined;
+}>;
+export declare function claimAgentGatewayEvents(input: {
+    agent_id: string;
+    after_seq?: number | string | null;
+    limit?: number | string | null;
+    claim_lease_id?: string | null;
+    client?: PoolClient;
+}): Promise<{
+    ok: true;
+    claim_lease_id: string;
+    items: AgentGatewayEventSnapshot[];
+}>;
+export declare function ackAgentGatewayEvents(input: {
+    agent_id: string;
+    acks: Array<{
+        event_id: string;
+        status: string;
+        last_error?: string | null;
+        result?: Record<string, unknown> | null;
+        retry_after_ms?: number | string | null;
+    }>;
+    client?: PoolClient;
+}): Promise<{
+    ok: true;
+    items: AgentGatewayEventSnapshot[];
+}>;
+//# sourceMappingURL=agentGatewayEvents.d.ts.map

package/dist/services/agentGatewayEvents.d.ts.map

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

package/dist/services/agentGatewayEvents.js

@@ -0,0 +1,258 @@
+import { nanoid } from 'nanoid';
+import { buildAgentEventFetchUri, normalizeAgentEventAckStatus, normalizeAgentEventStatus, normalizeAgentGatewayPreview, normalizeAgentGatewayResourceRef, normalizeAgentGatewayTopic, normalizeText, parseAgentEventAfterSeq, parseAgentEventBatchLimit, parseAgentEventRetryAfterMs, } from '@hirey/hi-agent-contracts';
+import { query, withTransaction } from '../db/pg.js';
+import { nowISO } from '../utils/time.js';
+const AGENT_EVENT_STALE_PROCESSING_MS = 10 * 60_000;
+const MAX_ERROR_LENGTH = 1000;
+function parseJsonObject(input) {
+    if (!input)
+        return null;
+    if (typeof input === 'object' && !Array.isArray(input))
+        return input;
+    if (typeof input !== 'string')
+        return null;
+    try {
+        const parsed = JSON.parse(String(input));
+        return parsed && typeof parsed === 'object' && !Array.isArray(parsed)
+            ? parsed
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+function mapAgentGatewayEventRow(row) {
+    const topic = normalizeAgentGatewayTopic(row?.topic || row?.event_type);
+    return {
+        event_id: normalizeText(row?.event_id),
+        target_agent_id: normalizeText(row?.target_agent_id),
+        stream_seq: Number(row?.stream_seq || 0),
+        topic,
+        event_type: topic,
+        occurred_at: row?.occurred_at ? String(row.occurred_at) : null,
+        resource_ref: normalizeAgentGatewayResourceRef(parseJsonObject(row?.resource_ref_json)),
+        preview: normalizeAgentGatewayPreview(parseJsonObject(row?.preview_json)),
+        fetch_uri: buildAgentEventFetchUri(normalizeText(row?.event_id)),
+        idempotency_key: normalizeText(row?.idempotency_key) || null,
+        status: normalizeAgentEventStatus(row?.status),
+        attempts: Math.max(0, Number(row?.attempts || 0)),
+        available_at: row?.available_at ? String(row.available_at) : null,
+        processing_started_at: row?.processing_started_at ? String(row.processing_started_at) : null,
+        claimed_by_agent_id: normalizeText(row?.claimed_by_agent_id) || null,
+        claimed_by_lease_id: normalizeText(row?.claimed_by_lease_id) || null,
+        claimed_at: row?.claimed_at ? String(row.claimed_at) : null,
+        consumed_at: row?.consumed_at ? String(row.consumed_at) : null,
+        last_error: row?.last_error ? String(row.last_error) : null,
+        result: parseJsonObject(row?.result_json),
+        payload: parseJsonObject(row?.payload_json),
+        created_at: row?.created_at ? String(row.created_at) : null,
+        updated_at: row?.updated_at ? String(row.updated_at) : null,
+    };
+}
+async function withOptionalClient(client, fn) {
+    if (client)
+        return await fn(client);
+    return await withTransaction(fn);
+}
+export async function createAgentGatewayEvent(input) {
+    const targetAgentId = normalizeText(input.target_agent_id);
+    if (!targetAgentId)
+        throw new Error('missing_target_agent_id');
+    const topic = normalizeAgentGatewayTopic(input.topic || input.event_type);
+    const payload = input.payload && typeof input.payload === 'object' && !Array.isArray(input.payload)
+        ? input.payload
+        : null;
+    if (!payload)
+        throw new Error('invalid_agent_gateway_payload');
+    const resourceRef = normalizeAgentGatewayResourceRef(input.resource_ref);
+    const preview = normalizeAgentGatewayPreview(input.preview);
+    const idempotencyKey = normalizeText(input.idempotency_key) || null;
+    const eventStatus = normalizeAgentEventStatus(input.status);
+    return await withOptionalClient(input.client, async (client) => {
+        const eventId = `aevt_${nanoid(12)}`;
+        const now = nowISO();
+        const occurredAt = normalizeText(input.occurred_at) || now;
+        const insertResult = (await query(`INSERT INTO agent_event_outbox (
+         event_id, target_agent_id, topic, event_type, occurred_at,
+         resource_ref_json, preview_json, payload_json, idempotency_key,
+         status, attempts, available_at, processing_started_at,
+         claimed_by_agent_id, claimed_by_lease_id, claimed_at, consumed_at,
+         last_error, result_json, created_at, updated_at
+       ) VALUES (
+         $1,$2,$3,$3,$4,
+         $5,$6,$7,$8,
+         $9,0,$10,NULL,
+         NULL,NULL,NULL,NULL,
+         NULL,NULL,$10,$10
+       )
+       ON CONFLICT (target_agent_id, idempotency_key) DO NOTHING
+       RETURNING *`, [
+            eventId,
+            targetAgentId,
+            topic,
+            occurredAt,
+            JSON.stringify(resourceRef),
+            preview ? JSON.stringify(preview) : null,
+            JSON.stringify(payload),
+            idempotencyKey,
+            eventStatus,
+            now,
+        ], client)).rows[0];
+        if (insertResult?.event_id) {
+            return {
+                ok: true,
+                duplicate: false,
+                event: mapAgentGatewayEventRow(insertResult),
+            };
+        }
+        if (!idempotencyKey) {
+            throw new Error('agent_gateway_event_insert_failed');
+        }
+        const existing = (await query(`SELECT *
+         FROM agent_event_outbox
+        WHERE target_agent_id=$1
+          AND idempotency_key=$2
+        LIMIT 1`, [targetAgentId, idempotencyKey], client)).rows[0];
+        if (!existing?.event_id)
+            throw new Error('agent_gateway_event_insert_failed');
+        return {
+            ok: true,
+            duplicate: true,
+            event: mapAgentGatewayEventRow(existing),
+        };
+    });
+}
+export async function listAgentGatewayEventEnvelopes(input) {
+    const agentId = normalizeText(input.agent_id);
+    if (!agentId)
+        throw new Error('missing_agent_id');
+    const afterSeq = parseAgentEventAfterSeq(input.after_seq);
+    const limit = parseAgentEventBatchLimit(input.limit, 100, 200);
+    const rows = (await query(`SELECT *
+       FROM agent_event_outbox
+      WHERE target_agent_id=$1
+        AND stream_seq > $2
+      ORDER BY stream_seq ASC
+      LIMIT $3`, [agentId, afterSeq, limit], input.client)).rows;
+    return {
+        ok: true,
+        items: rows.map((row) => {
+            const snapshot = mapAgentGatewayEventRow(row);
+            const { status: _status, attempts: _attempts, available_at: _availableAt, processing_started_at: _processingStartedAt, claimed_by_agent_id: _claimedByAgentId, claimed_by_lease_id: _claimedByLeaseId, claimed_at: _claimedAt, consumed_at: _consumedAt, last_error: _lastError, result: _result, payload: _payload, created_at: _createdAt, updated_at: _updatedAt, ...envelope } = snapshot;
+            return envelope;
+        }),
+    };
+}
+export async function getAgentGatewayEventById(input) {
+    const agentId = normalizeText(input.agent_id);
+    const eventId = normalizeText(input.event_id);
+    if (!agentId || !eventId)
+        throw new Error('missing_agent_event_lookup_keys');
+    const row = (await query(`SELECT *
+       FROM agent_event_outbox
+      WHERE event_id=$1
+        AND target_agent_id=$2
+      LIMIT 1`, [eventId, agentId], input.client)).rows[0];
+    if (!row?.event_id)
+        return { ok: false, error: 'agent_event_not_found' };
+    return { ok: true, event: mapAgentGatewayEventRow(row) };
+}
+export async function claimAgentGatewayEvents(input) {
+    const agentId = normalizeText(input.agent_id);
+    if (!agentId)
+        throw new Error('missing_agent_id');
+    const afterSeq = parseAgentEventAfterSeq(input.after_seq);
+    const limit = parseAgentEventBatchLimit(input.limit, 20, 100);
+    const claimLeaseId = normalizeText(input.claim_lease_id) || `lease_${nanoid(12)}`;
+    return await withOptionalClient(input.client, async (client) => {
+        const now = nowISO();
+        const staleThreshold = new Date(Date.now() - AGENT_EVENT_STALE_PROCESSING_MS).toISOString();
+        const rows = (await query(`SELECT event_id
+         FROM agent_event_outbox
+        WHERE target_agent_id=$1
+          AND stream_seq > $2
+          AND (
+            (status='queued' AND available_at <= $3)
+            OR (status='failed' AND available_at <= $3)
+            OR (
+              status='processing'
+              AND processing_started_at IS NOT NULL
+              AND processing_started_at <= $4
+            )
+          )
+        ORDER BY stream_seq ASC
+        LIMIT $5
+        FOR UPDATE SKIP LOCKED`, [agentId, afterSeq, now, staleThreshold, limit], client)).rows;
+        const items = [];
+        for (const row of rows) {
+            const updated = (await query(`UPDATE agent_event_outbox
+            SET status='processing',
+                attempts=attempts + 1,
+                processing_started_at=$2,
+                claimed_by_agent_id=$3,
+                claimed_by_lease_id=$4,
+                claimed_at=$2,
+                updated_at=$2
+          WHERE event_id=$1
+          RETURNING *`, [normalizeText(row.event_id), now, agentId, claimLeaseId], client)).rows[0];
+            if (updated?.event_id)
+                items.push(mapAgentGatewayEventRow(updated));
+        }
+        return {
+            ok: true,
+            claim_lease_id: claimLeaseId,
+            items,
+        };
+    });
+}
+export async function ackAgentGatewayEvents(input) {
+    const agentId = normalizeText(input.agent_id);
+    if (!agentId)
+        throw new Error('missing_agent_id');
+    if (!Array.isArray(input.acks) || input.acks.length === 0)
+        throw new Error('missing_agent_event_acks');
+    return await withOptionalClient(input.client, async (client) => {
+        const items = [];
+        const now = nowISO();
+        for (const ack of input.acks.slice(0, 100)) {
+            const eventId = normalizeText(ack?.event_id);
+            if (!eventId)
+                continue;
+            const status = normalizeAgentEventAckStatus(ack?.status);
+            const retryAfterMs = parseAgentEventRetryAfterMs(ack?.retry_after_ms);
+            const nextAvailableAt = (status === 'failed' && retryAfterMs != null
+                ? new Date(Date.now() + retryAfterMs).toISOString()
+                : now);
+            const row = (await query(`UPDATE agent_event_outbox
+            SET status=$3,
+                available_at=$4,
+                processing_started_at=NULL,
+                claimed_by_agent_id=$2,
+                claimed_by_lease_id=NULL,
+                claimed_at=CASE WHEN status='processing' THEN COALESCE(claimed_at, $5) ELSE claimed_at END,
+                consumed_at=CASE WHEN $3='consumed' THEN $5 ELSE NULL END,
+                last_error=$6,
+                result_json=$7,
+                updated_at=$5
+          WHERE event_id=$1
+            AND target_agent_id=$2
+          RETURNING *`, [
+                eventId,
+                agentId,
+                status,
+                nextAvailableAt,
+                now,
+                ack?.last_error ? String(ack.last_error).slice(0, MAX_ERROR_LENGTH) : null,
+                ack?.result && typeof ack.result === 'object' && !Array.isArray(ack.result)
+                    ? JSON.stringify(ack.result)
+                    : null,
+            ], client)).rows[0];
+            if (row?.event_id)
+                items.push(mapAgentGatewayEventRow(row));
+        }
+        return {
+            ok: true,
+            items,
+        };
+    });
+}

package/dist/utils/agentId.d.ts

@@ -0,0 +1,2 @@
+export declare function normalizeAgentId(raw: unknown): string | null;
+//# sourceMappingURL=agentId.d.ts.map

package/dist/utils/agentId.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agentId.d.ts","sourceRoot":"","sources":["../../src/utils/agentId.ts"],"names":[],"mappings":"AAKA,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAI5D"}

package/dist/utils/agentId.js

@@ -0,0 +1,10 @@
+function normalizeText(raw) {
+    return typeof raw === 'string' ? raw.trim() : '';
+}
+// 平台 agent 的正式对外标识统一使用 ag_*。
+export function normalizeAgentId(raw) {
+    const value = normalizeText(raw);
+    if (!value)
+        return null;
+    return value.startsWith('ag_') ? value : null;
+}

package/dist/utils/time.d.ts

@@ -0,0 +1,2 @@
+export declare function nowISO(): string;
+//# sourceMappingURL=time.d.ts.map

package/dist/utils/time.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"time.d.ts","sourceRoot":"","sources":["../../src/utils/time.ts"],"names":[],"mappings":"AACA,wBAAgB,MAAM,IAAI,MAAM,CAE/B"}

package/dist/utils/time.js

@@ -0,0 +1,4 @@
+// 统一 ISO 时间戳，避免不同 repo/服务层各自实现。
+export function nowISO() {
+    return new Date().toISOString();
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@hirey/hi-agent-delivery",
+  "version": "0.1.3",
+  "private": false,
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist/",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./payloads": {
+      "types": "./dist/payloads.d.ts",
+      "default": "./dist/payloads.js"
+    }
+  },
+  "scripts": {
+    "clean": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
+    "build": "npm run clean && tsc -p tsconfig.json",
+    "prepack": "npm run build"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@hirey/hi-agent-contracts": "^0.1.8",
+    "nanoid": "^5.0.7",
+    "pg": "^8.11.3"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.30",
+    "@types/pg": "^8.6.6",
+    "typescript": "^5.4.5"
+  }
+}