@pcircle/memesh 4.7.3 → 4.8.0

package/dist/core/agent-message-storage.d.ts

@@ -0,0 +1,76 @@
+import type { MemeshDatabase } from '../storage/sqlite.js';
+export interface AgentMessageStorageReportOptions {
+    cutoff: Date | string;
+    databasePath?: string;
+}
+export interface AgentMessageStorageReport {
+    message_count: number;
+    delivery_count: number;
+    event_count: number;
+    receipt_count: number;
+    cursor_count: number;
+    principal_count: number;
+    session_instance_count: number;
+    session_connection_count: number;
+    presence_fact_count: number;
+    dispatch_attempt_count: number;
+    host_accept_count: number;
+    ack_fact_count: number;
+    workflow_fact_count: number;
+    retention_fact_count: number;
+    payload_bytes: number;
+    original_payload_bytes: number;
+    tombstoned_message_count: number;
+    protected_unresolved_message_count: number;
+    terminal_retained_message_count: number;
+    terminal_prunable_message_count: number;
+    terminal_prunable_payload_bytes: number;
+    reconciled_message_count: number;
+    page_count: number;
+    page_size: number;
+    freelist_count: number;
+    allocated_database_bytes: number;
+    reusable_freelist_bytes: number;
+    database_file_bytes: number | null;
+    wal_file_bytes: number | null;
+}
+export interface AgentMessageRetentionOptions extends AgentMessageStorageReportOptions {
+    batchSize?: number;
+    dryRun?: boolean;
+    actor?: string;
+    fault?: {
+        beforeTombstone?(candidate: AgentMessageRetentionCandidate): void;
+    };
+}
+export interface AgentMessageRetentionCandidate {
+    message_id: string;
+    payload_bytes: number;
+    payload_sha256: string;
+}
+export interface AgentMessageRetentionResult {
+    dry_run: boolean;
+    candidate_count: number;
+    tombstoned_count: number;
+    reclaimed_payload_bytes: number;
+    candidates: AgentMessageRetentionCandidate[];
+}
+export interface AgentMessageStorageQuotaInput {
+    quotaBytes: number;
+    additionalPayloadBytes: number;
+}
+export declare class AgentMessageStorageError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+export declare class AgentMessageStorageQuotaExceededError extends AgentMessageStorageError {
+    readonly quotaBytes: number;
+    readonly usedBytes: number;
+    readonly requestedBytes: number;
+    constructor(quotaBytes: number, usedBytes: number, requestedBytes: number);
+}
+export declare function getAgentMessageStorageReport(db: MemeshDatabase, options: AgentMessageStorageReportOptions): AgentMessageStorageReport;
+export declare function pruneTerminalAgentMessagePayloads(db: MemeshDatabase, options: AgentMessageRetentionOptions): AgentMessageRetentionResult;
+export declare function enforceAgentMessageStorageQuota(db: MemeshDatabase, input: AgentMessageStorageQuotaInput): void;
+export declare function agentMessagePayloadStorageBytes(payloadJson: string): number;
+export declare const AGENT_MESSAGE_TERMINAL_WORKFLOW_STATES: readonly string[];
+//# sourceMappingURL=agent-message-storage.d.ts.map

package/dist/core/agent-message-storage.d.ts.map

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

package/dist/core/agent-message-storage.js

@@ -0,0 +1,359 @@
+import { createHash, randomUUID } from 'node:crypto';
+import fs from 'node:fs';
+const TERMINAL_WORKFLOW_STATES = new Set(['completed', 'cancelled', 'rejected']);
+const DEFAULT_BATCH_SIZE = 100;
+const MAX_BATCH_SIZE = 1_000;
+export class AgentMessageStorageError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'AgentMessageStorageError';
+        this.code = code;
+    }
+}
+export class AgentMessageStorageQuotaExceededError extends AgentMessageStorageError {
+    quotaBytes;
+    usedBytes;
+    requestedBytes;
+    constructor(quotaBytes, usedBytes, requestedBytes) {
+        super('storage_quota_exceeded', 'Agent message storage quota exceeded.');
+        this.name = 'AgentMessageStorageQuotaExceededError';
+        this.quotaBytes = quotaBytes;
+        this.usedBytes = usedBytes;
+        this.requestedBytes = requestedBytes;
+    }
+}
+export function getAgentMessageStorageReport(db, options) {
+    const cutoff = normalizeCutoff(options.cutoff);
+    const states = readMessageStates(db, cutoff);
+    const lifecycle = db.prepare(`
+    SELECT
+      (SELECT COUNT(*) FROM agent_message_deliveries) AS delivery_count,
+      (SELECT COUNT(*) FROM agent_message_events) AS event_count,
+      (SELECT COUNT(*) FROM agent_message_receipts) AS receipt_count,
+      (SELECT COUNT(*) FROM agent_message_cursors) AS cursor_count,
+      (SELECT COUNT(*) FROM agent_principals) AS principal_count,
+      (SELECT COUNT(*) FROM agent_session_instances) AS session_instance_count,
+      (SELECT COUNT(*) FROM agent_session_connections) AS session_connection_count,
+      (SELECT COUNT(*) FROM agent_presence_facts) AS presence_fact_count,
+      (SELECT COUNT(*) FROM agent_dispatch_attempts) AS dispatch_attempt_count,
+      (SELECT COUNT(*) FROM agent_host_accepts) AS host_accept_count,
+      (SELECT COUNT(*) FROM agent_ack_facts) AS ack_fact_count,
+      (SELECT COUNT(*) FROM agent_workflow_facts) AS workflow_fact_count,
+      (SELECT COUNT(*) FROM agent_retention_facts) AS retention_fact_count
+  `).get();
+    const pageCount = pragmaInteger(db, 'page_count');
+    const pageSize = pragmaInteger(db, 'page_size');
+    const freelistCount = pragmaInteger(db, 'freelist_count');
+    return {
+        message_count: states.message_count,
+        delivery_count: lifecycle.delivery_count,
+        event_count: lifecycle.event_count,
+        receipt_count: lifecycle.receipt_count,
+        cursor_count: lifecycle.cursor_count,
+        principal_count: lifecycle.principal_count,
+        session_instance_count: lifecycle.session_instance_count,
+        session_connection_count: lifecycle.session_connection_count,
+        presence_fact_count: lifecycle.presence_fact_count,
+        dispatch_attempt_count: lifecycle.dispatch_attempt_count,
+        host_accept_count: lifecycle.host_accept_count,
+        ack_fact_count: lifecycle.ack_fact_count,
+        workflow_fact_count: lifecycle.workflow_fact_count,
+        retention_fact_count: lifecycle.retention_fact_count,
+        payload_bytes: states.payload_bytes,
+        original_payload_bytes: states.original_payload_bytes,
+        tombstoned_message_count: states.tombstoned_message_count,
+        protected_unresolved_message_count: states.protected_unresolved_message_count,
+        terminal_retained_message_count: states.terminal_retained_message_count,
+        terminal_prunable_message_count: states.terminal_prunable_message_count,
+        terminal_prunable_payload_bytes: states.terminal_prunable_payload_bytes,
+        reconciled_message_count: states.reconciled_message_count,
+        page_count: pageCount,
+        page_size: pageSize,
+        freelist_count: freelistCount,
+        allocated_database_bytes: pageCount * pageSize,
+        reusable_freelist_bytes: freelistCount * pageSize,
+        database_file_bytes: safeFileSize(options.databasePath),
+        wal_file_bytes: options.databasePath ? safeFileSize(`${options.databasePath}-wal`) : null,
+    };
+}
+export function pruneTerminalAgentMessagePayloads(db, options) {
+    const cutoff = normalizeCutoff(options.cutoff);
+    const batchSize = normalizeBatchSize(options.batchSize);
+    const dryRun = options.dryRun === undefined ? true : options.dryRun;
+    const actor = normalizeActor(options.actor);
+    if (dryRun) {
+        const candidates = selectPrunableMessages(db, cutoff, batchSize).map(toCandidate);
+        return resultForCandidates(true, candidates);
+    }
+    return db.transaction(() => {
+        const selected = selectPrunableMessages(db, cutoff, batchSize);
+        const candidates = selected.map(toCandidate);
+        for (let index = 0; index < selected.length; index++) {
+            const candidate = candidates[index];
+            options.fault?.beforeTombstone?.(candidate);
+            const tombstone = stableTombstone(candidate.payload_sha256, candidate.payload_bytes);
+            const result = db.prepare(`
+        UPDATE agent_messages
+        SET payload_json = ?, payload_sha256 = ?, payload_original_bytes = ?, payload_tombstoned_at = CURRENT_TIMESTAMP
+        WHERE message_id = ? AND payload_tombstoned_at IS NULL
+      `).run(tombstone, candidate.payload_sha256, candidate.payload_bytes, candidate.message_id);
+            if (result.changes !== 1) {
+                throw new AgentMessageStorageError('retention_concurrent_change', 'Agent message retention candidate changed during pruning.');
+            }
+            insertRetentionFact(db, candidate, actor, tombstone);
+        }
+        return resultForCandidates(false, candidates);
+    }).immediate();
+}
+export function enforceAgentMessageStorageQuota(db, input) {
+    const quotaBytes = normalizeNonNegativeInteger('quotaBytes', input.quotaBytes);
+    const additionalPayloadBytes = normalizeNonNegativeInteger('additionalPayloadBytes', input.additionalPayloadBytes);
+    const row = db.prepare(`
+    SELECT COALESCE(SUM(length(CAST(payload_json AS BLOB))), 0) AS payload_bytes
+    FROM agent_messages
+  `).get();
+    const usedBytes = row.payload_bytes;
+    if (usedBytes + additionalPayloadBytes > quotaBytes) {
+        throw new AgentMessageStorageQuotaExceededError(quotaBytes, usedBytes, additionalPayloadBytes);
+    }
+}
+export function agentMessagePayloadStorageBytes(payloadJson) {
+    if (typeof payloadJson !== 'string') {
+        throw new AgentMessageStorageError('invalid_payload_storage_input', 'Agent message payload JSON must be a string.');
+    }
+    return Buffer.byteLength(payloadJson, 'utf8');
+}
+function readMessageStates(db, cutoff) {
+    return db.prepare(`
+    WITH workflow_candidates AS (
+      SELECT delivery_id, workflow_state, created_at
+      FROM agent_workflow_facts
+      UNION ALL
+      SELECT d.delivery_id, json_extract(r.detail_json, '$.disposition') AS workflow_state,
+        r.created_at
+      FROM agent_message_receipts r
+      JOIN agent_message_deliveries d
+        ON d.message_id = r.message_id AND d.project = r.project AND d.recipient = r.recipient
+      WHERE r.receipt_kind = 'disposition'
+    ), ranked_workflow AS (
+      SELECT delivery_id, workflow_state, created_at,
+        DENSE_RANK() OVER (
+          PARTITION BY delivery_id
+          ORDER BY julianday(created_at) DESC
+        ) AS time_rank
+      FROM workflow_candidates
+    ), latest_workflow AS (
+      SELECT delivery_id,
+        CASE WHEN SUM(CASE
+          WHEN workflow_state IN ('completed', 'cancelled', 'rejected') THEN 0 ELSE 1
+        END) = 0 THEN 1 ELSE 0 END AS is_terminal,
+        MAX(created_at) AS created_at
+      FROM ranked_workflow
+      WHERE time_rank = 1
+      GROUP BY delivery_id
+    ), acknowledged_deliveries AS (
+      SELECT delivery_id
+      FROM agent_ack_facts
+      UNION
+      SELECT d.delivery_id
+      FROM agent_message_receipts r
+      JOIN agent_message_deliveries d
+        ON d.message_id = r.message_id AND d.project = r.project AND d.recipient = r.recipient
+      WHERE r.receipt_kind = 'ack'
+    ), delivery_states AS (
+      SELECT d.message_id,
+        COUNT(*) AS delivery_count,
+        SUM(CASE WHEN acknowledged_deliveries.delivery_id IS NOT NULL THEN 1 ELSE 0 END) AS acknowledged_count,
+        SUM(CASE WHEN lw.is_terminal = 1 THEN 1 ELSE 0 END) AS terminal_count,
+        SUM(CASE WHEN lw.is_terminal = 1
+                      AND julianday(lw.created_at) < julianday(?) THEN 1 ELSE 0 END) AS old_terminal_count
+      FROM agent_message_deliveries d
+      LEFT JOIN acknowledged_deliveries ON acknowledged_deliveries.delivery_id = d.delivery_id
+      LEFT JOIN latest_workflow lw ON lw.delivery_id = d.delivery_id
+      GROUP BY d.message_id
+    ), message_states AS (
+      SELECT m.message_id, length(CAST(m.payload_json AS BLOB)) AS payload_bytes,
+        COALESCE(m.payload_original_bytes, length(CAST(m.payload_json AS BLOB))) AS original_payload_bytes,
+        CASE
+          WHEN m.payload_tombstoned_at IS NOT NULL THEN 'tombstoned'
+          WHEN COALESCE(ds.delivery_count, 0) > 0
+               AND ds.acknowledged_count = ds.delivery_count
+               AND ds.terminal_count = ds.delivery_count
+               AND ds.old_terminal_count = ds.delivery_count THEN 'prunable'
+          WHEN COALESCE(ds.delivery_count, 0) > 0
+               AND ds.acknowledged_count = ds.delivery_count
+               AND ds.terminal_count = ds.delivery_count THEN 'terminal_retained'
+          ELSE 'protected'
+        END AS storage_state
+      FROM agent_messages m
+      LEFT JOIN delivery_states ds ON ds.message_id = m.message_id
+    )
+    SELECT
+      COUNT(*) AS message_count,
+      COALESCE(SUM(payload_bytes), 0) AS payload_bytes,
+      COALESCE(SUM(original_payload_bytes), 0) AS original_payload_bytes,
+      COALESCE(SUM(storage_state = 'tombstoned'), 0) AS tombstoned_message_count,
+      COALESCE(SUM(storage_state = 'protected'), 0) AS protected_unresolved_message_count,
+      COALESCE(SUM(storage_state = 'terminal_retained'), 0) AS terminal_retained_message_count,
+      COALESCE(SUM(storage_state = 'prunable'), 0) AS terminal_prunable_message_count,
+      COALESCE(SUM(CASE WHEN storage_state = 'prunable' THEN payload_bytes ELSE 0 END), 0) AS terminal_prunable_payload_bytes,
+      COALESCE(SUM(storage_state IN ('tombstoned', 'protected', 'terminal_retained', 'prunable')), 0) AS reconciled_message_count
+    FROM message_states
+  `).get(cutoff);
+}
+function selectPrunableMessages(db, cutoff, batchSize) {
+    return db.prepare(`
+    WITH workflow_candidates AS (
+      SELECT delivery_id, workflow_state, created_at
+      FROM agent_workflow_facts
+      UNION ALL
+      SELECT d.delivery_id, json_extract(r.detail_json, '$.disposition') AS workflow_state,
+        r.created_at
+      FROM agent_message_receipts r
+      JOIN agent_message_deliveries d
+        ON d.message_id = r.message_id AND d.project = r.project AND d.recipient = r.recipient
+      WHERE r.receipt_kind = 'disposition'
+    ), ranked_workflow AS (
+      SELECT delivery_id, workflow_state, created_at,
+        DENSE_RANK() OVER (
+          PARTITION BY delivery_id
+          ORDER BY julianday(created_at) DESC
+        ) AS time_rank
+      FROM workflow_candidates
+    ), latest_workflow AS (
+      SELECT delivery_id,
+        CASE WHEN SUM(CASE
+          WHEN workflow_state IN ('completed', 'cancelled', 'rejected') THEN 0 ELSE 1
+        END) = 0 THEN 1 ELSE 0 END AS is_terminal,
+        MAX(created_at) AS created_at
+      FROM ranked_workflow
+      WHERE time_rank = 1
+      GROUP BY delivery_id
+    ), acknowledged_deliveries AS (
+      SELECT delivery_id
+      FROM agent_ack_facts
+      UNION
+      SELECT d.delivery_id
+      FROM agent_message_receipts r
+      JOIN agent_message_deliveries d
+        ON d.message_id = r.message_id AND d.project = r.project AND d.recipient = r.recipient
+      WHERE r.receipt_kind = 'ack'
+    ), delivery_states AS (
+      SELECT d.message_id,
+        COUNT(*) AS delivery_count,
+        SUM(CASE WHEN acknowledged_deliveries.delivery_id IS NOT NULL THEN 1 ELSE 0 END) AS acknowledged_count,
+        SUM(CASE WHEN lw.is_terminal = 1
+                      AND julianday(lw.created_at) < julianday(?) THEN 1 ELSE 0 END) AS old_terminal_count
+      FROM agent_message_deliveries d
+      LEFT JOIN acknowledged_deliveries ON acknowledged_deliveries.delivery_id = d.delivery_id
+      LEFT JOIN latest_workflow lw ON lw.delivery_id = d.delivery_id
+      GROUP BY d.message_id
+    )
+    SELECT m.message_id, m.payload_json, length(CAST(m.payload_json AS BLOB)) AS payload_bytes
+    FROM agent_messages m
+    JOIN delivery_states ds ON ds.message_id = m.message_id
+    WHERE m.payload_tombstoned_at IS NULL
+      AND ds.delivery_count > 0
+      AND ds.acknowledged_count = ds.delivery_count
+      AND ds.old_terminal_count = ds.delivery_count
+    ORDER BY m.created_at ASC, m.message_id ASC
+    LIMIT ?
+  `).all(cutoff, batchSize);
+}
+function toCandidate(row) {
+    return {
+        message_id: row.message_id,
+        payload_bytes: row.payload_bytes,
+        payload_sha256: createHash('sha256').update(row.payload_json, 'utf8').digest('hex'),
+    };
+}
+function resultForCandidates(dryRun, candidates) {
+    return {
+        dry_run: dryRun,
+        candidate_count: candidates.length,
+        tombstoned_count: dryRun ? 0 : candidates.length,
+        reclaimed_payload_bytes: reclaimedPayloadBytes(candidates),
+        candidates,
+    };
+}
+function reclaimedPayloadBytes(candidates) {
+    const netPayloadBytes = candidates.reduce((total, candidate) => {
+        const tombstone = stableTombstone(candidate.payload_sha256, candidate.payload_bytes);
+        return total + candidate.payload_bytes - Buffer.byteLength(tombstone, 'utf8');
+    }, 0);
+    return Math.max(0, netPayloadBytes);
+}
+function insertRetentionFact(db, candidate, actor, tombstone) {
+    const idempotencyKey = `payload-tombstone:${candidate.message_id}:${candidate.payload_sha256}`;
+    const detailJson = JSON.stringify({
+        algorithm: 'sha256',
+        original_payload_bytes: candidate.payload_bytes,
+        payload_sha256: candidate.payload_sha256,
+        tombstone_payload_bytes: Buffer.byteLength(tombstone, 'utf8'),
+    });
+    const requestHash = createHash('sha256').update(detailJson, 'utf8').digest('hex');
+    db.prepare(`
+    INSERT INTO agent_retention_facts (
+      retention_fact_id, message_id, actor, retention_state, idempotency_key, request_hash, detail_json
+    ) VALUES (?, ?, ?, 'payload_tombstoned', ?, ?, ?)
+  `).run(randomUUID(), candidate.message_id, actor, idempotencyKey, requestHash, detailJson);
+}
+function stableTombstone(payloadHash, originalPayloadBytes) {
+    return JSON.stringify({
+        _agent_message_tombstone_v1: {
+            algorithm: 'sha256',
+            original_payload_bytes: originalPayloadBytes,
+            payload_sha256: payloadHash,
+        },
+    });
+}
+function normalizeCutoff(value) {
+    const date = value instanceof Date ? value : new Date(value);
+    if (Number.isNaN(date.getTime())) {
+        throw new AgentMessageStorageError('invalid_retention_cutoff', 'Agent message retention cutoff must be a valid date.');
+    }
+    return date.toISOString();
+}
+function normalizeBatchSize(value) {
+    if (value === undefined)
+        return DEFAULT_BATCH_SIZE;
+    if (!Number.isInteger(value) || value < 1 || value > MAX_BATCH_SIZE) {
+        throw new AgentMessageStorageError('invalid_retention_batch_size', `Agent message retention batch size must be between 1 and ${MAX_BATCH_SIZE}.`);
+    }
+    return value;
+}
+function normalizeActor(value) {
+    const actor = (value ?? 'agent-message-retention-v1').trim();
+    if (actor.length === 0 || actor.length > 200) {
+        throw new AgentMessageStorageError('invalid_retention_actor', 'Agent message retention actor must be 1 to 200 characters.');
+    }
+    return actor;
+}
+function normalizeNonNegativeInteger(label, value) {
+    if (!Number.isSafeInteger(value) || value < 0) {
+        throw new AgentMessageStorageError('invalid_storage_quota', `${label} must be a non-negative safe integer.`);
+    }
+    return value;
+}
+function pragmaInteger(db, pragma) {
+    const row = db.prepare(`PRAGMA ${pragma}`).get();
+    const value = row[pragma];
+    if (!Number.isSafeInteger(value) || value < 0) {
+        throw new AgentMessageStorageError('invalid_storage_pragma', `SQLite PRAGMA ${pragma} returned an invalid value.`);
+    }
+    return value;
+}
+function safeFileSize(filePath) {
+    if (!filePath)
+        return null;
+    try {
+        const stat = fs.statSync(filePath);
+        return stat.isFile() ? stat.size : null;
+    }
+    catch {
+        return null;
+    }
+}
+export const AGENT_MESSAGE_TERMINAL_WORKFLOW_STATES = [...TERMINAL_WORKFLOW_STATES];
+//# sourceMappingURL=agent-message-storage.js.map

package/dist/core/agent-message-storage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-message-storage.js","sourceRoot":"","sources":["../../src/core/agent-message-storage.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACrD,OAAO,EAAE,MAAM,SAAS,CAAC;AAIzB,MAAM,wBAAwB,GAAG,IAAI,GAAG,CAAC,CAAC,WAAW,EAAE,WAAW,EAAE,UAAU,CAAC,CAAC,CAAC;AACjF,MAAM,kBAAkB,GAAG,GAAG,CAAC;AAC/B,MAAM,cAAc,GAAG,KAAK,CAAC;AA+E7B,MAAM,OAAO,wBAAyB,SAAQ,KAAK;IACxC,IAAI,CAAS;IAEtB,YAAY,IAAY,EAAE,OAAe;QACvC,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,0BAA0B,CAAC;QACvC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF;AAGD,MAAM,OAAO,qCAAsC,SAAQ,wBAAwB;IACxE,UAAU,CAAS;IACnB,SAAS,CAAS;IAClB,cAAc,CAAS;IAEhC,YAAY,UAAkB,EAAE,SAAiB,EAAE,cAAsB;QACvE,KAAK,CAAC,wBAAwB,EAAE,uCAAuC,CAAC,CAAC;QACzE,IAAI,CAAC,IAAI,GAAG,uCAAuC,CAAC;QACpD,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;QAC7B,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;QAC3B,IAAI,CAAC,cAAc,GAAG,cAAc,CAAC;IACvC,CAAC;CACF;AAOD,MAAM,UAAU,4BAA4B,CAC1C,EAAkB,EAClB,OAAyC;IAEzC,MAAM,MAAM,GAAG,eAAe,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IAC/C,MAAM,MAAM,GAAG,iBAAiB,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC;IAC7C,MAAM,SAAS,GAAG,EAAE,CAAC,OAAO,CAAC;;;;;;;;;;;;;;;GAe5B,CAAC,CAAC,GAAG,EAAqB,CAAC;IAC5B,MAAM,SAAS,GAAG,aAAa,CAAC,EAAE,EAAE,YAAY,CAAC,CAAC;IAClD,MAAM,QAAQ,GAAG,aAAa,CAAC,EAAE,EAAE,WAAW,CAAC,CAAC;IAChD,MAAM,aAAa,GAAG,aAAa,CAAC,EAAE,EAAE,gBAAgB,CAAC,CAAC;IAE1D,OAAO;QACL,aAAa,EAAE,MAAM,CAAC,aAAa;QACnC,cAAc,EAAE,SAAS,CAAC,cAAc;QACxC,WAAW,EAAE,SAAS,CAAC,WAAW;QAClC,aAAa,EAAE,SAAS,CAAC,aAAa;QACtC,YAAY,EAAE,SAAS,CAAC,YAAY;QACpC,eAAe,EAAE,SAAS,CAAC,eAAe;QAC1C,sBAAsB,EAAE,SAAS,CAAC,sBAAsB;QACxD,wBAAwB,EAAE,SAAS,CAAC,wBAAwB;QAC5D,mBAAmB,EAAE,SAAS,CAAC,mBAAmB;QAClD,sBAAsB,EAAE,SAAS,CAAC,sBAAsB;QACxD,iBAAiB,EAAE,SAAS,CAAC,iBAAiB;QAC9C,cAAc,EAAE,SAAS,CAAC,cAAc;QACxC,mBAAmB,EAAE,SAAS,CAAC,mBAAmB;QAClD,oBAAoB,EAAE,SAAS,CAAC,oBAAoB;QACpD,aAAa,EAAE,MAAM,CAAC,aAAa;QACnC,sBAAsB,EAAE,MAAM,CAAC,sBAAsB;QACrD,wBAAwB,EAAE,MAAM,CAAC,wBAAwB;QACzD,kCAAkC,EAAE,MAAM,CAAC,kCAAkC;QAC7E,+BAA+B,EAAE,MAAM,CAAC,+BAA+B;QACvE,+BAA+B,EAAE,MAAM,CAAC,+BAA+B;QACvE,+BAA+B,EAAE,MAAM,CAAC,+BAA+B;QACvE,wBAAwB,EAAE,MAAM,CAAC,wBAAwB;QACzD,UAAU,EAAE,SAAS;QACrB,SAAS,EAAE,QAAQ;QACnB,cAAc,EAAE,aAAa;QAC7B,wBAAwB,EAAE,SAAS,GAAG,QAAQ;QAC9C,uBAAuB,EAAE,aAAa,GAAG,QAAQ;QACjD,mBAAmB,EAAE,YAAY,CAAC,OAAO,CAAC,YAAY,CAAC;QACvD,cAAc,EAAE,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,YAAY,CAAC,GAAG,OAAO,CAAC,YAAY,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI;KAC1F,CAAC;AACJ,CAAC;AAMD,MAAM,UAAU,iCAAiC,CAC/C,EAAkB,EAClB,OAAqC;IAErC,MAAM,MAAM,GAAG,eAAe,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IAC/C,MAAM,SAAS,GAAG,kBAAkB,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IACxD,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC;IACpE,MAAM,KAAK,GAAG,cAAc,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;IAE5C,IAAI,MAAM,EAAE,CAAC;QACX,MAAM,UAAU,GAAG,sBAAsB,CAAC,EAAE,EAAE,MAAM,EAAE,SAAS,CAAC,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;QAClF,OAAO,mBAAmB,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;IAC/C,CAAC;IAED,OAAO,EAAE,CAAC,WAAW,CAAC,GAAG,EAAE;QACzB,MAAM,QAAQ,GAAG,sBAAsB,CAAC,EAAE,EAAE,MAAM,EAAE,SAAS,CAAC,CAAC;QAC/D,MAAM,UAAU,GAAG,QAAQ,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;QAC7C,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,QAAQ,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE,CAAC;YACrD,MAAM,SAAS,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC;YACpC,OAAO,CAAC,KAAK,EAAE,eAAe,EAAE,CAAC,SAAS,CAAC,CAAC;YAC5C,MAAM,SAAS,GAAG,eAAe,CAAC,SAAS,CAAC,cAAc,EAAE,SAAS,CAAC,aAAa,CAAC,CAAC;YACrF,MAAM,MAAM,GAAG,EAAE,CAAC,OAAO,CAAC;;;;OAIzB,CAAC,CAAC,GAAG,CAAC,SAAS,EAAE,SAAS,CAAC,cAAc,EAAE,SAAS,CAAC,aAAa,EAAE,SAAS,CAAC,UAAU,CAAC,CAAC;YAC3F,IAAI,MAAM,CAAC,OAAO,KAAK,CAAC,EAAE,CAAC;gBACzB,MAAM,IAAI,wBAAwB,CAAC,6BAA6B,EAAE,2DAA2D,CAAC,CAAC;YACjI,CAAC;YACD,mBAAmB,CAAC,EAAE,EAAE,SAAS,EAAE,KAAK,EAAE,SAAS,CAAC,CAAC;QACvD,CAAC;QACD,OAAO,mBAAmB,CAAC,KAAK,EAAE,UAAU,CAAC,CAAC;IAChD,CAAC,CAAC,CAAC,SAAS,EAAE,CAAC;AACjB,CAAC;AAQD,MAAM,UAAU,+BAA+B,CAC7C,EAAkB,EAClB,KAAoC;IAEpC,MAAM,UAAU,GAAG,2BAA2B,CAAC,YAAY,EAAE,KAAK,CAAC,UAAU,CAAC,CAAC;IAC/E,MAAM,sBAAsB,GAAG,2BAA2B,CAAC,wBAAwB,EAAE,KAAK,CAAC,sBAAsB,CAAC,CAAC;IACnH,MAAM,GAAG,GAAG,EAAE,CAAC,OAAO,CAAC;;;GAGtB,CAAC,CAAC,GAAG,EAA+B,CAAC;IACtC,MAAM,SAAS,GAAG,GAAG,CAAC,aAAa,CAAC;IACpC,IAAI,SAAS,GAAG,sBAAsB,GAAG,UAAU,EAAE,CAAC;QACpD,MAAM,IAAI,qCAAqC,CAAC,UAAU,EAAE,SAAS,EAAE,sBAAsB,CAAC,CAAC;IACjG,CAAC;AACH,CAAC;AAGD,MAAM,UAAU,+BAA+B,CAAC,WAAmB;IACjE,IAAI,OAAO,WAAW,KAAK,QAAQ,EAAE,CAAC;QACpC,MAAM,IAAI,wBAAwB,CAAC,+BAA+B,EAAE,8CAA8C,CAAC,CAAC;IACtH,CAAC;IACD,OAAO,MAAM,CAAC,UAAU,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC;AAChD,CAAC;AAoCD,SAAS,iBAAiB,CAAC,EAAkB,EAAE,MAAc;IAC3D,OAAO,EAAE,CAAC,OAAO,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2EjB,CAAC,CAAC,GAAG,CAAC,MAAM,CAAuB,CAAC;AACvC,CAAC;AAED,SAAS,sBAAsB,CAAC,EAAkB,EAAE,MAAc,EAAE,SAAiB;IACnF,OAAO,EAAE,CAAC,OAAO,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDjB,CAAC,CAAC,GAAG,CAAC,MAAM,EAAE,SAAS,CAAyB,CAAC;AACpD,CAAC;AAED,SAAS,WAAW,CAAC,GAAuB;IAC1C,OAAO;QACL,UAAU,EAAE,GAAG,CAAC,UAAU;QAC1B,aAAa,EAAE,GAAG,CAAC,aAAa;QAChC,cAAc,EAAE,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC;KACpF,CAAC;AACJ,CAAC;AAED,SAAS,mBAAmB,CAAC,MAAe,EAAE,UAA4C;IACxF,OAAO;QACL,OAAO,EAAE,MAAM;QACf,eAAe,EAAE,UAAU,CAAC,MAAM;QAClC,gBAAgB,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,MAAM;QAChD,uBAAuB,EAAE,qBAAqB,CAAC,UAAU,CAAC;QAC1D,UAAU;KACX,CAAC;AACJ,CAAC;AAED,SAAS,qBAAqB,CAAC,UAA4C;IACzE,MAAM,eAAe,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,SAAS,EAAE,EAAE;QAC7D,MAAM,SAAS,GAAG,eAAe,CAAC,SAAS,CAAC,cAAc,EAAE,SAAS,CAAC,aAAa,CAAC,CAAC;QACrF,OAAO,KAAK,GAAG,SAAS,CAAC,aAAa,GAAG,MAAM,CAAC,UAAU,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;IAChF,CAAC,EAAE,CAAC,CAAC,CAAC;IACN,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,eAAe,CAAC,CAAC;AACtC,CAAC;AAED,SAAS,mBAAmB,CAC1B,EAAkB,EAClB,SAAyC,EACzC,KAAa,EACb,SAAiB;IAEjB,MAAM,cAAc,GAAG,qBAAqB,SAAS,CAAC,UAAU,IAAI,SAAS,CAAC,cAAc,EAAE,CAAC;IAC/F,MAAM,UAAU,GAAG,IAAI,CAAC,SAAS,CAAC;QAChC,SAAS,EAAE,QAAQ;QACnB,sBAAsB,EAAE,SAAS,CAAC,aAAa;QAC/C,cAAc,EAAE,SAAS,CAAC,cAAc;QACxC,uBAAuB,EAAE,MAAM,CAAC,UAAU,CAAC,SAAS,EAAE,MAAM,CAAC;KAC9D,CAAC,CAAC;IACH,MAAM,WAAW,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAClF,EAAE,CAAC,OAAO,CAAC;;;;GAIV,CAAC,CAAC,GAAG,CAAC,UAAU,EAAE,EAAE,SAAS,CAAC,UAAU,EAAE,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,UAAU,CAAC,CAAC;AAC7F,CAAC;AAED,SAAS,eAAe,CAAC,WAAmB,EAAE,oBAA4B;IACxE,OAAO,IAAI,CAAC,SAAS,CAAC;QACpB,2BAA2B,EAAE;YAC3B,SAAS,EAAE,QAAQ;YACnB,sBAAsB,EAAE,oBAAoB;YAC5C,cAAc,EAAE,WAAW;SAC5B;KACF,CAAC,CAAC;AACL,CAAC;AAED,SAAS,eAAe,CAAC,KAAoB;IAC3C,MAAM,IAAI,GAAG,KAAK,YAAY,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,KAAK,CAAC,CAAC;IAC7D,IAAI,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,EAAE,CAAC;QACjC,MAAM,IAAI,wBAAwB,CAAC,0BAA0B,EAAE,sDAAsD,CAAC,CAAC;IACzH,CAAC;IACD,OAAO,IAAI,CAAC,WAAW,EAAE,CAAC;AAC5B,CAAC;AAED,SAAS,kBAAkB,CAAC,KAAyB;IACnD,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,kBAAkB,CAAC;IACnD,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,IAAI,KAAK,GAAG,cAAc,EAAE,CAAC;QACpE,MAAM,IAAI,wBAAwB,CAAC,8BAA8B,EAAE,4DAA4D,cAAc,GAAG,CAAC,CAAC;IACpJ,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,cAAc,CAAC,KAAyB;IAC/C,MAAM,KAAK,GAAG,CAAC,KAAK,IAAI,4BAA4B,CAAC,CAAC,IAAI,EAAE,CAAC;IAC7D,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,IAAI,KAAK,CAAC,MAAM,GAAG,GAAG,EAAE,CAAC;QAC7C,MAAM,IAAI,wBAAwB,CAAC,yBAAyB,EAAE,4DAA4D,CAAC,CAAC;IAC9H,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,2BAA2B,CAAC,KAAa,EAAE,KAAa;IAC/D,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;QAC9C,MAAM,IAAI,wBAAwB,CAAC,uBAAuB,EAAE,GAAG,KAAK,uCAAuC,CAAC,CAAC;IAC/G,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,aAAa,CAAC,EAAkB,EAAE,MAAc;IACvD,MAAM,GAAG,GAAG,EAAE,CAAC,OAAO,CAAC,UAAU,MAAM,EAAE,CAAC,CAAC,GAAG,EAA4B,CAAC;IAC3E,MAAM,KAAK,GAAG,GAAG,CAAC,MAAM,CAAC,CAAC;IAC1B,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;QAC9C,MAAM,IAAI,wBAAwB,CAAC,wBAAwB,EAAE,iBAAiB,MAAM,6BAA6B,CAAC,CAAC;IACrH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,YAAY,CAAC,QAA4B;IAChD,IAAI,CAAC,QAAQ;QAAE,OAAO,IAAI,CAAC;IAC3B,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,EAAE,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;QACnC,OAAO,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;IAC1C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAID,MAAM,CAAC,MAAM,sCAAsC,GAAG,CAAC,GAAG,wBAAwB,CAAU,CAAC"}

package/dist/core/agent-messaging.d.ts

@@ -0,0 +1,224 @@
+import type { MemeshDatabase } from '../storage/sqlite.js';
+export type AgentJsonPrimitive = boolean | null | number | string;
+export type AgentJsonValue = AgentJsonPrimitive | AgentJsonValue[] | {
+    [key: string]: AgentJsonValue;
+};
+export type AgentJsonObject = {
+    [key: string]: AgentJsonValue;
+};
+export type AgentMessagePrivacy = 'private' | 'team';
+export type AgentContentType = 'text/plain' | 'application/json';
+export type AgentTargetKind = 'principal' | 'session';
+export type AgentReceiptKind = 'intake' | 'ack' | 'disposition' | 'host_activation';
+export type AgentIntakeState = 'fetched' | 'ingested';
+export type AgentDisposition = 'accepted' | 'rejected' | 'cancelled' | 'completed' | 'deferred';
+export type AgentHostActivation = 'woken' | 'manual_resume_required' | 'unsupported' | 'failed';
+export interface SendAgentMessageInput {
+    project: string;
+    sender: string;
+    recipient: string;
+    target_kind?: AgentTargetKind;
+    idempotency_key: string;
+    payload: AgentJsonValue;
+    content_type: AgentContentType;
+    sender_host?: string | null;
+    correlation_id?: string | null;
+    reply_to?: string | null;
+    privacy?: AgentMessagePrivacy;
+    provenance?: AgentJsonObject;
+}
+export interface SentAgentMessage {
+    message_id: string;
+    delivery_id: string;
+    event_id: string;
+    project: string;
+    sender: string;
+    sender_host: string | null;
+    recipient: string;
+    target_kind: AgentTargetKind;
+    content_type: AgentContentType;
+    correlation_id: string | null;
+    reply_to: string | null;
+    privacy: AgentMessagePrivacy;
+    created_at: string;
+    provenance: AgentJsonObject;
+}
+export interface AgentMessagePostCommitHint {
+    delivery_id: string;
+    event_id: string;
+    project: string;
+    target_kind: AgentTargetKind;
+    target_id: string;
+}
+export interface AgentMessagePostCommitNotifier {
+    notify(hint: AgentMessagePostCommitHint): void | Promise<void>;
+}
+export interface SendAgentMessageOptions {
+    notifier?: AgentMessagePostCommitNotifier;
+    storage_quota_bytes?: number;
+}
+export interface PollAgentEventsInput {
+    project: string;
+    recipient: string;
+    cursor?: string | null;
+    limit?: number;
+}
+export interface AgentMessageEventHeader {
+    event_id: string;
+    message_id: string;
+    sender: string;
+    sender_host: string | null;
+    recipient: string;
+    target_kind: AgentTargetKind;
+    content_type: AgentContentType;
+    correlation_id: string | null;
+    reply_to: string | null;
+    privacy: AgentMessagePrivacy;
+    created_at: string;
+}
+export interface PollAgentEventsResult {
+    events: AgentMessageEventHeader[];
+    next_cursor: string;
+}
+export interface WaitForAgentEventsInput extends PollAgentEventsInput {
+    wait_ms?: number;
+    poll_interval_ms?: number;
+}
+export interface FetchAgentMessageInput {
+    project: string;
+    recipient: string;
+    message_id: string;
+    target_kind?: AgentTargetKind;
+}
+export interface AgentMessagePayload {
+    message_id: string;
+    project: string;
+    sender: string;
+    sender_host: string | null;
+    recipient: string;
+    target_kind: AgentTargetKind;
+    content_type: AgentContentType;
+    correlation_id: string | null;
+    reply_to: string | null;
+    privacy: AgentMessagePrivacy;
+    created_at: string;
+    payload: AgentJsonValue;
+    provenance: AgentJsonObject;
+}
+interface AgentReceiptBase {
+    project: string;
+    recipient: string;
+    message_id: string;
+    actor: string;
+    idempotency_key: string;
+    detail?: AgentJsonObject;
+}
+export type RecordAgentReceiptInput = (AgentReceiptBase & {
+    receipt_kind: 'intake';
+    intake_state: AgentIntakeState;
+}) | (AgentReceiptBase & {
+    receipt_kind: 'ack';
+}) | (AgentReceiptBase & {
+    receipt_kind: 'disposition';
+    disposition: AgentDisposition;
+}) | (AgentReceiptBase & {
+    receipt_kind: 'host_activation';
+    host_activation: AgentHostActivation;
+});
+interface AgentReceiptRowBase {
+    receipt_id: string;
+    message_id: string;
+    project: string;
+    recipient: string;
+    actor: string;
+    idempotency_key: string;
+    created_at: string;
+}
+export type AgentMessageReceipt = (AgentReceiptRowBase & {
+    receipt_kind: 'intake';
+    intake_state: AgentIntakeState;
+    detail: AgentJsonObject;
+}) | (AgentReceiptRowBase & {
+    receipt_kind: 'ack';
+    detail: AgentJsonObject;
+}) | (AgentReceiptRowBase & {
+    receipt_kind: 'disposition';
+    disposition: AgentDisposition;
+    detail: AgentJsonObject;
+}) | (AgentReceiptRowBase & {
+    receipt_kind: 'host_activation';
+    host_activation: AgentHostActivation;
+    detail: AgentJsonObject;
+});
+export interface ReadAgentMessageReceiptsInput {
+    project: string;
+    recipient: string;
+    message_id: string;
+}
+export interface RecordAgentAckFactInput {
+    delivery_id: string;
+    host_accept_id: string;
+    actor: string;
+    idempotency_key: string;
+    detail?: AgentJsonObject;
+}
+export interface AgentAckFact {
+    ack_fact_id: string;
+    delivery_id: string;
+    host_accept_id: string;
+    actor: string;
+    idempotency_key: string;
+    detail: AgentJsonObject;
+    created_at: string;
+}
+export interface RecordAgentWorkflowFactInput {
+    delivery_id: string;
+    actor: string;
+    workflow_state: string;
+    idempotency_key: string;
+    detail?: AgentJsonObject;
+}
+export interface AgentWorkflowFact {
+    workflow_fact_id: string;
+    delivery_id: string;
+    actor: string;
+    workflow_state: string;
+    idempotency_key: string;
+    detail: AgentJsonObject;
+    created_at: string;
+}
+export interface RecordAgentRetentionFactInput {
+    message_id: string;
+    actor: string;
+    retention_state: string;
+    idempotency_key: string;
+    detail?: AgentJsonObject;
+}
+export interface AgentRetentionFact {
+    retention_fact_id: string;
+    message_id: string;
+    actor: string;
+    retention_state: string;
+    idempotency_key: string;
+    detail: AgentJsonObject;
+    created_at: string;
+}
+export declare class AgentMessagingError extends Error {
+}
+export declare class AgentIdempotencyConflictError extends AgentMessagingError {
+}
+export declare class AgentMessageAccessError extends AgentMessagingError {
+}
+export declare class AgentWaitAbortedError extends AgentMessagingError {
+}
+export declare function sendAgentMessage(db: MemeshDatabase, input: SendAgentMessageInput, options?: SendAgentMessageOptions): SentAgentMessage;
+export declare function pollAgentEvents(db: MemeshDatabase, input: PollAgentEventsInput): PollAgentEventsResult;
+export declare function waitForAgentEvents(db: MemeshDatabase, input: WaitForAgentEventsInput, signal?: AbortSignal): Promise<PollAgentEventsResult>;
+export declare function fetchAgentMessage(db: MemeshDatabase, input: FetchAgentMessageInput): AgentMessagePayload;
+export declare function recordAgentReceipt(db: MemeshDatabase, input: RecordAgentReceiptInput): AgentMessageReceipt;
+export declare function readAgentMessageReceipts(db: MemeshDatabase, input: ReadAgentMessageReceiptsInput): AgentMessageReceipt[];
+export declare function recordAgentAckFact(db: MemeshDatabase, input: RecordAgentAckFactInput): AgentAckFact;
+export declare function recordAgentWorkflowFact(db: MemeshDatabase, input: RecordAgentWorkflowFactInput): AgentWorkflowFact;
+export declare function recordAgentRetentionFact(db: MemeshDatabase, input: RecordAgentRetentionFactInput): AgentRetentionFact;
+export {};
+//# sourceMappingURL=agent-messaging.d.ts.map