@revealui/ai 0.1.0

package/dist/a2a/handler.js

@@ -0,0 +1,170 @@
+/**
+ * A2A JSON-RPC Handler
+ *
+ * Dispatches A2A JSON-RPC 2.0 methods to the appropriate implementation.
+ * Integrates with AgentRuntime and AgentOrchestrator from @revealui/ai/orchestration.
+ *
+ * Supported methods:
+ *   tasks/send          — synchronous task execution
+ *   tasks/get           — retrieve task by ID
+ *   tasks/cancel        — cancel a running task
+ *   tasks/sendSubscribe — (handled at route level via SSE; returns taskId here)
+ */
+import { A2ASendTaskParamsSchema } from '@revealui/contracts';
+import { logger } from '@revealui/core/observability/logger';
+import { agentCardRegistry } from './card.js';
+import { appendArtifact, cancelTask, createTask, getTask, getTaskSignal, updateTaskState, } from './task-store.js';
+// =============================================================================
+// JSON-RPC error codes (A2A uses standard JSON-RPC codes + custom range -32000+)
+// =============================================================================
+const RPC_PARSE_ERROR = -32700;
+const RPC_INVALID_REQUEST = -32600;
+const RPC_METHOD_NOT_FOUND = -32601;
+const RPC_INVALID_PARAMS = -32602;
+const RPC_TASK_NOT_FOUND = -32001;
+const RPC_TASK_NOT_CANCELABLE = -32002;
+const RPC_AGENT_NOT_FOUND = -32003;
+// =============================================================================
+// Response helpers
+// =============================================================================
+function ok(id, result) {
+    return { jsonrpc: '2.0', id, result };
+}
+function err(id, code, message, data) {
+    return { jsonrpc: '2.0', id, error: { code, message, data } };
+}
+// =============================================================================
+// Method handlers
+// =============================================================================
+async function handleTasksSend(id, params, agentId, llmClient) {
+    const parsed = A2ASendTaskParamsSchema.safeParse(params);
+    if (!parsed.success) {
+        return err(id, RPC_INVALID_PARAMS, 'Invalid tasks/send params', parsed.error.issues);
+    }
+    const p = parsed.data;
+    // Validate agent exists if agentId provided
+    if (agentId && !agentCardRegistry.has(agentId)) {
+        return err(id, RPC_AGENT_NOT_FOUND, `Agent '${agentId}' not found`);
+    }
+    // Create task in submitted state
+    const task = createTask({
+        id: p.id,
+        sessionId: p.sessionId,
+        message: p.message,
+        metadata: p.metadata,
+    });
+    const signal = getTaskSignal(task.id);
+    try {
+        // Transition to working
+        updateTaskState(task.id, 'working');
+        // Execute via orchestration — for now, produce a direct text response.
+        // Full AgentRuntime integration wires in when an LLM provider is configured.
+        const agentDef = agentId
+            ? agentCardRegistry.getDef(agentId)
+            : agentCardRegistry.getDef('revealui-creator');
+        if (signal?.aborted) {
+            return ok(id, getTask(task.id));
+        }
+        // Build response message
+        const textInput = p.message.parts
+            .filter((part) => part.type === 'text')
+            .map((part) => ('text' in part ? part.text : ''))
+            .join('\n')
+            .trim();
+        let responseText;
+        if (llmClient && textInput) {
+            // Real LLM call using the provided client
+            const messages = [];
+            if (agentDef?.systemPrompt) {
+                messages.push({ role: 'system', content: agentDef.systemPrompt });
+            }
+            messages.push({ role: 'user', content: textInput });
+            const llmResponse = await llmClient.chat(messages);
+            responseText = llmResponse.content;
+        }
+        else {
+            // Stub response when no LLM client is configured
+            responseText = agentDef
+                ? `[${agentDef.name}] Received: "${textInput}". Task queued for execution. ` +
+                    `Capabilities: ${agentDef.capabilities.join(', ')}.`
+                : `Task received: "${textInput}". Processing...`;
+        }
+        const agentMessage = {
+            role: 'agent',
+            parts: [{ type: 'text', text: responseText }],
+        };
+        // Append artifact and complete
+        appendArtifact(task.id, {
+            name: 'response',
+            parts: [{ type: 'text', text: responseText }],
+            index: 0,
+            lastChunk: true,
+        });
+        const completed = updateTaskState(task.id, 'completed', agentMessage);
+        logger.info(`A2A task ${task.id} completed`);
+        return ok(id, completed);
+    }
+    catch (e) {
+        const message = e instanceof Error ? e.message : 'Task execution failed';
+        logger.error(`A2A task ${task.id} failed: ${message}`);
+        const failed = updateTaskState(task.id, 'failed', {
+            role: 'agent',
+            parts: [{ type: 'text', text: `Error: ${message}` }],
+        });
+        return ok(id, failed);
+    }
+}
+function handleTasksGet(id, params) {
+    const p = params;
+    const taskId = p?.id;
+    if (typeof taskId !== 'string') {
+        return err(id, RPC_INVALID_PARAMS, 'params.id (string) is required');
+    }
+    const task = getTask(taskId);
+    if (!task) {
+        return err(id, RPC_TASK_NOT_FOUND, `Task '${taskId}' not found`);
+    }
+    return ok(id, task);
+}
+function handleTasksCancel(id, params) {
+    const p = params;
+    const taskId = p?.id;
+    if (typeof taskId !== 'string') {
+        return err(id, RPC_INVALID_PARAMS, 'params.id (string) is required');
+    }
+    const canceled = cancelTask(taskId);
+    if (!canceled) {
+        const task = getTask(taskId);
+        if (!task)
+            return err(id, RPC_TASK_NOT_FOUND, `Task '${taskId}' not found`);
+        return err(id, RPC_TASK_NOT_CANCELABLE, `Task '${taskId}' is not in a cancelable state`);
+    }
+    return ok(id, getTask(taskId));
+}
+// =============================================================================
+// Main dispatcher
+// =============================================================================
+/**
+ * Handle an A2A JSON-RPC request and return a JSON-RPC response.
+ *
+ * @param req - Parsed JSON-RPC request body
+ * @param agentId - Optional agent ID (from X-Agent-ID header)
+ * @param llmClient - Optional LLM client for real inference (BYOK)
+ */
+export async function handleA2AJsonRpc(req, agentId, llmClient) {
+    const { id, method, params } = req;
+    switch (method) {
+        case 'tasks/send':
+            return handleTasksSend(id, params, agentId, llmClient);
+        case 'tasks/get':
+            return handleTasksGet(id, params);
+        case 'tasks/cancel':
+            return handleTasksCancel(id, params);
+        case 'tasks/sendSubscribe':
+            // SSE streaming is handled at the Hono route level; return a reference task here
+            return handleTasksSend(id, params, agentId, llmClient);
+        default:
+            return err(id, RPC_METHOD_NOT_FOUND, `Method '${method}' not found`);
+    }
+}
+export { RPC_PARSE_ERROR, RPC_INVALID_REQUEST };

package/dist/a2a/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @revealui/ai — A2A Protocol Implementation
+ *
+ * Agent-to-Agent (A2A) protocol support for RevealUI.
+ * Exports the agent card registry, task store, and JSON-RPC handler.
+ */
+export { agentCardRegistry } from './card.js';
+export { handleA2AJsonRpc, RPC_INVALID_REQUEST, RPC_PARSE_ERROR } from './handler.js';
+export { appendArtifact, cancelTask, createTask, evictTask, getTask, getTaskSignal, updateTaskState, } from './task-store.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/a2a/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/a2a/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAA;AAC7C,OAAO,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,eAAe,EAAE,MAAM,cAAc,CAAA;AACrF,OAAO,EACL,cAAc,EACd,UAAU,EACV,UAAU,EACV,SAAS,EACT,OAAO,EACP,aAAa,EACb,eAAe,GAChB,MAAM,iBAAiB,CAAA"}

package/dist/a2a/index.js

@@ -0,0 +1,9 @@
+/**
+ * @revealui/ai — A2A Protocol Implementation
+ *
+ * Agent-to-Agent (A2A) protocol support for RevealUI.
+ * Exports the agent card registry, task store, and JSON-RPC handler.
+ */
+export { agentCardRegistry } from './card.js';
+export { handleA2AJsonRpc, RPC_INVALID_REQUEST, RPC_PARSE_ERROR } from './handler.js';
+export { appendArtifact, cancelTask, createTask, evictTask, getTask, getTaskSignal, updateTaskState, } from './task-store.js';

package/dist/a2a/task-store.d.ts

@@ -0,0 +1,42 @@
+/**
+ * A2A Task Store
+ *
+ * In-memory store for A2A task state. Tasks are short-lived (lifetime of a
+ * request or streaming session) so persistence is not needed here.
+ * The authoritative record for completed tasks lives in @revealui/db (agentActions).
+ */
+import type { A2AArtifact, A2AMessage, A2ATask, A2ATaskState } from '@revealui/contracts';
+/**
+ * Create a new task in the 'submitted' state.
+ */
+export declare function createTask(params: {
+    id?: string;
+    sessionId?: string;
+    message: A2AMessage;
+    metadata?: Record<string, unknown>;
+}): A2ATask;
+/**
+ * Get a task by ID.
+ */
+export declare function getTask(id: string): A2ATask | null;
+/**
+ * Transition a task to a new state, optionally attaching a message.
+ */
+export declare function updateTaskState(id: string, state: A2ATaskState, message?: A2AMessage): A2ATask | null;
+/**
+ * Append an artifact to a completed task.
+ */
+export declare function appendArtifact(id: string, artifact: A2AArtifact): A2ATask | null;
+/**
+ * Cancel a task. Returns true if the task was cancelable.
+ */
+export declare function cancelTask(id: string): boolean;
+/**
+ * Get the AbortSignal for a running task (so the executor can detect cancellation).
+ */
+export declare function getTaskSignal(id: string): AbortSignal | null;
+/**
+ * Cleanup a task from the store (call after response has been sent).
+ */
+export declare function evictTask(id: string): void;
+//# sourceMappingURL=task-store.d.ts.map

package/dist/a2a/task-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"task-store.d.ts","sourceRoot":"","sources":["../../src/a2a/task-store.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AAUzF;;GAEG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE;IACjC,EAAE,CAAC,EAAE,MAAM,CAAA;IACX,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,OAAO,EAAE,UAAU,CAAA;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACnC,GAAG,OAAO,CAeV;AAED;;GAEG;AACH,wBAAgB,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,GAAG,IAAI,CAElD;AAED;;GAEG;AACH,wBAAgB,eAAe,CAC7B,EAAE,EAAE,MAAM,EACV,KAAK,EAAE,YAAY,EACnB,OAAO,CAAC,EAAE,UAAU,GACnB,OAAO,GAAG,IAAI,CAehB;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,WAAW,GAAG,OAAO,GAAG,IAAI,CAUhF;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAY9C;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,EAAE,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,CAE5D;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAG1C"}

package/dist/a2a/task-store.js

@@ -0,0 +1,99 @@
+/**
+ * A2A Task Store
+ *
+ * In-memory store for A2A task state. Tasks are short-lived (lifetime of a
+ * request or streaming session) so persistence is not needed here.
+ * The authoritative record for completed tasks lives in @revealui/db (agentActions).
+ */
+// Map of abort controllers so callers can cancel running tasks
+const _controllers = new Map();
+const _tasks = new Map();
+function now() {
+    return new Date().toISOString();
+}
+/**
+ * Create a new task in the 'submitted' state.
+ */
+export function createTask(params) {
+    const id = params.id ?? crypto.randomUUID();
+    const task = {
+        id,
+        sessionId: params.sessionId,
+        status: {
+            state: 'submitted',
+            timestamp: now(),
+        },
+        history: [params.message],
+        metadata: params.metadata,
+    };
+    _tasks.set(id, task);
+    _controllers.set(id, new AbortController());
+    return task;
+}
+/**
+ * Get a task by ID.
+ */
+export function getTask(id) {
+    return _tasks.get(id) ?? null;
+}
+/**
+ * Transition a task to a new state, optionally attaching a message.
+ */
+export function updateTaskState(id, state, message) {
+    const task = _tasks.get(id);
+    if (!task)
+        return null;
+    const updated = {
+        ...task,
+        status: {
+            state,
+            message,
+            timestamp: now(),
+        },
+        history: message ? [...(task.history ?? []), message] : task.history,
+    };
+    _tasks.set(id, updated);
+    return updated;
+}
+/**
+ * Append an artifact to a completed task.
+ */
+export function appendArtifact(id, artifact) {
+    const task = _tasks.get(id);
+    if (!task)
+        return null;
+    const updated = {
+        ...task,
+        artifacts: [...(task.artifacts ?? []), artifact],
+    };
+    _tasks.set(id, updated);
+    return updated;
+}
+/**
+ * Cancel a task. Returns true if the task was cancelable.
+ */
+export function cancelTask(id) {
+    const task = _tasks.get(id);
+    if (!task)
+        return false;
+    const cancelable = task.status.state === 'submitted' || task.status.state === 'working';
+    if (!cancelable)
+        return false;
+    // Signal abort to any running execution
+    _controllers.get(id)?.abort();
+    updateTaskState(id, 'canceled');
+    return true;
+}
+/**
+ * Get the AbortSignal for a running task (so the executor can detect cancellation).
+ */
+export function getTaskSignal(id) {
+    return _controllers.get(id)?.signal ?? null;
+}
+/**
+ * Cleanup a task from the store (call after response has been sent).
+ */
+export function evictTask(id) {
+    _tasks.delete(id);
+    _controllers.delete(id);
+}

package/dist/audit/emitter.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Audit Emitter
+ *
+ * Write-only interface for agents. Agents can emit events but cannot
+ * read, query, modify, or delete audit entries. This enforces the
+ * separation between agent execution and human oversight.
+ *
+ * The emitter is created by the AuditObserver and injected into agents
+ * via the runtime. Agents never have access to the observer itself.
+ */
+import type { AuditEventType, AuditSeverity } from './types.js';
+/**
+ * Write-only audit interface provided to agents.
+ * This is the ONLY audit API agents can access.
+ */
+export interface AuditEmitter {
+    /**
+     * Emit an audit event. This is a fire-and-forget operation —
+     * the agent does not receive confirmation or any data back.
+     */
+    emit(eventType: AuditEventType, payload: Record<string, unknown>, severity?: AuditSeverity): void;
+}
+/** Internal handler signature used by the observer to receive emitted events */
+export type AuditEmitHandler = (agentId: string, eventType: AuditEventType, payload: Record<string, unknown>, severity: AuditSeverity) => void;
+/**
+ * Creates a frozen, write-only AuditEmitter bound to a specific agent.
+ * The returned object is frozen to prevent agents from modifying it.
+ *
+ * @param agentId - The agent this emitter is scoped to
+ * @param handler - Internal handler that routes events to the observer
+ * @returns A frozen, write-only AuditEmitter
+ */
+export declare function createAuditEmitter(agentId: string, handler: AuditEmitHandler): AuditEmitter;
+//# sourceMappingURL=emitter.d.ts.map

package/dist/audit/emitter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"emitter.d.ts","sourceRoot":"","sources":["../../src/audit/emitter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAI/D;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B;;;OAGG;IACH,IAAI,CAAC,SAAS,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,QAAQ,CAAC,EAAE,aAAa,GAAG,IAAI,CAAA;CAClG;AAID,gFAAgF;AAChF,MAAM,MAAM,gBAAgB,GAAG,CAC7B,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,cAAc,EACzB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,QAAQ,EAAE,aAAa,KACpB,IAAI,CAAA;AAIT;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,gBAAgB,GAAG,YAAY,CAkB3F"}

package/dist/audit/emitter.js

@@ -0,0 +1,34 @@
+/**
+ * Audit Emitter
+ *
+ * Write-only interface for agents. Agents can emit events but cannot
+ * read, query, modify, or delete audit entries. This enforces the
+ * separation between agent execution and human oversight.
+ *
+ * The emitter is created by the AuditObserver and injected into agents
+ * via the runtime. Agents never have access to the observer itself.
+ */
+// ─── Emitter Factory ────────────────────────────────────────────────────────
+/**
+ * Creates a frozen, write-only AuditEmitter bound to a specific agent.
+ * The returned object is frozen to prevent agents from modifying it.
+ *
+ * @param agentId - The agent this emitter is scoped to
+ * @param handler - Internal handler that routes events to the observer
+ * @returns A frozen, write-only AuditEmitter
+ */
+export function createAuditEmitter(agentId, handler) {
+    const emitter = {
+        emit(eventType, payload, severity = 'info') {
+            // Fire-and-forget — agents don't get feedback from the audit system
+            try {
+                handler(agentId, eventType, payload, severity);
+            }
+            catch {
+                // Silently swallow errors — audit failures must never affect agent execution
+            }
+        },
+    };
+    // Freeze to prevent agents from replacing or extending the emitter
+    return Object.freeze(emitter);
+}

package/dist/audit/index.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Audit Trail System
+ *
+ * Provides an immutable, append-only audit trail for all agent activity.
+ * Designed with strict separation of concerns:
+ *
+ * - **Agents** receive a write-only `AuditEmitter` (can emit events, nothing else)
+ * - **Humans** control the `AuditObserver` (query, policies, kill switches)
+ * - **Store** is append-only (no updates, no deletes)
+ *
+ * This architecture ensures that AI agents cannot tamper with, disable,
+ * or circumvent the audit trail — it lives entirely outside their scope.
+ *
+ * ## Quick Start
+ *
+ * ```typescript
+ * import { AuditObserver, InMemoryAuditStore, builtinPolicies } from '@revealui/ai'
+ *
+ * // Human sets up the observer (agents never see this)
+ * const observer = new AuditObserver({
+ *   store: new InMemoryAuditStore(),
+ *   onAlert: (alert) => logger.warn('ALERT:', alert),
+ *   onAgentHalted: (id, reason) => logger.warn(`Agent ${id} halted: ${reason}`),
+ * })
+ *
+ * // Add safety policies
+ * observer.addPolicy(builtinPolicies.toolCallRateLimit(100, 'admin'))
+ * observer.addPolicy(builtinPolicies.selfModificationBlock('admin'))
+ *
+ * // Create write-only emitter for an agent
+ * const emitter = observer.createEmitterForAgent('agent-1')
+ * // Pass `emitter` to the agent — it can only call emitter.emit()
+ *
+ * // Human can halt agents at any time
+ * observer.haltAgent('agent-1', 'admin', 'Suspicious behavior')
+ * observer.haltFleet('admin', 'Emergency stop')
+ * ```
+ */
+export { type AuditEmitHandler, type AuditEmitter, createAuditEmitter, } from './emitter.js';
+export { AuditObserver, type AuditObserverConfig, } from './observer.js';
+export { AuditPolicyEngine, builtinPolicies, } from './policy.js';
+export { type AuditStore, InMemoryAuditStore, } from './store.js';
+export { type AuditAgentStatus, type AuditAlert, type AuditEntry, AuditEntrySchema, AuditEventType, type AuditFilter, type AuditPolicy, AuditSeverity, PolicyAction, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/audit/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/audit/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAGH,OAAO,EACL,KAAK,gBAAgB,EACrB,KAAK,YAAY,EACjB,kBAAkB,GACnB,MAAM,cAAc,CAAA;AAErB,OAAO,EACL,aAAa,EACb,KAAK,mBAAmB,GACzB,MAAM,eAAe,CAAA;AAEtB,OAAO,EACL,iBAAiB,EACjB,eAAe,GAChB,MAAM,aAAa,CAAA;AAEpB,OAAO,EACL,KAAK,UAAU,EACf,kBAAkB,GACnB,MAAM,YAAY,CAAA;AAEnB,OAAO,EACL,KAAK,gBAAgB,EACrB,KAAK,UAAU,EACf,KAAK,UAAU,EACf,gBAAgB,EAChB,cAAc,EACd,KAAK,WAAW,EAChB,KAAK,WAAW,EAChB,aAAa,EACb,YAAY,GACb,MAAM,YAAY,CAAA"}

package/dist/audit/index.js

@@ -0,0 +1,48 @@
+/**
+ * Audit Trail System
+ *
+ * Provides an immutable, append-only audit trail for all agent activity.
+ * Designed with strict separation of concerns:
+ *
+ * - **Agents** receive a write-only `AuditEmitter` (can emit events, nothing else)
+ * - **Humans** control the `AuditObserver` (query, policies, kill switches)
+ * - **Store** is append-only (no updates, no deletes)
+ *
+ * This architecture ensures that AI agents cannot tamper with, disable,
+ * or circumvent the audit trail — it lives entirely outside their scope.
+ *
+ * ## Quick Start
+ *
+ * ```typescript
+ * import { AuditObserver, InMemoryAuditStore, builtinPolicies } from '@revealui/ai'
+ *
+ * // Human sets up the observer (agents never see this)
+ * const observer = new AuditObserver({
+ *   store: new InMemoryAuditStore(),
+ *   onAlert: (alert) => logger.warn('ALERT:', alert),
+ *   onAgentHalted: (id, reason) => logger.warn(`Agent ${id} halted: ${reason}`),
+ * })
+ *
+ * // Add safety policies
+ * observer.addPolicy(builtinPolicies.toolCallRateLimit(100, 'admin'))
+ * observer.addPolicy(builtinPolicies.selfModificationBlock('admin'))
+ *
+ * // Create write-only emitter for an agent
+ * const emitter = observer.createEmitterForAgent('agent-1')
+ * // Pass `emitter` to the agent — it can only call emitter.emit()
+ *
+ * // Human can halt agents at any time
+ * observer.haltAgent('agent-1', 'admin', 'Suspicious behavior')
+ * observer.haltFleet('admin', 'Emergency stop')
+ * ```
+ */
+// Emitter (write-only agent interface)
+export { createAuditEmitter, } from './emitter.js';
+// Observer (human-facing control plane)
+export { AuditObserver, } from './observer.js';
+// Policy engine
+export { AuditPolicyEngine, builtinPolicies, } from './policy.js';
+// Store (append-only persistence)
+export { InMemoryAuditStore, } from './store.js';
+// Types
+export { AuditEntrySchema, AuditEventType, AuditSeverity, PolicyAction, } from './types.js';

package/dist/audit/observer.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Audit Observer
+ *
+ * The central human-facing audit system. This is the ONLY component
+ * that has full read/write access to the audit trail. Agents never
+ * receive a reference to this object.
+ *
+ * Responsibilities:
+ * - Receives events from agent emitters
+ * - Stores entries in the append-only store
+ * - Evaluates policies and generates alerts
+ * - Tracks agent halt status
+ * - Provides query interface for human review
+ */
+import { type AuditEmitter } from './emitter.js';
+import type { AuditStore } from './store.js';
+import type { AuditAgentStatus, AuditAlert, AuditEntry, AuditFilter, AuditPolicy } from './types.js';
+export interface AuditObserverConfig {
+    /** Audit store backend */
+    store: AuditStore;
+    /** Number of recent entries to keep in memory for policy evaluation */
+    recentHistorySize?: number;
+    /** Callback when an alert is generated */
+    onAlert?: (alert: AuditAlert) => void;
+    /** Callback when an agent is halted */
+    onAgentHalted?: (agentId: string, reason: string) => void;
+    /** Callback when the entire fleet is halted */
+    onFleetHalted?: (reason: string) => void;
+}
+export declare class AuditObserver {
+    private store;
+    private policyEngine;
+    private recentHistory;
+    private recentHistorySize;
+    private agentStatus;
+    private fleetHalted;
+    private onAlert?;
+    private onAgentHalted?;
+    private onFleetHalted?;
+    constructor(config: AuditObserverConfig);
+    /**
+     * Create a write-only AuditEmitter for an agent.
+     * This is the only audit API agents should ever receive.
+     */
+    createEmitterForAgent(agentId: string): AuditEmitter;
+    private handleEvent;
+    /**
+     * Halt a specific agent. Only humans should call this.
+     */
+    haltAgent(agentId: string, haltedBy: string, reason: string): void;
+    /**
+     * Resume a halted agent. Only humans should call this.
+     */
+    resumeAgent(agentId: string, resumedBy: string): void;
+    /**
+     * Halt the entire agent fleet. Emergency stop.
+     */
+    haltFleet(haltedBy: string, reason: string): void;
+    /**
+     * Resume the entire fleet. Only humans should call this.
+     */
+    resumeFleet(resumedBy: string): void;
+    /**
+     * Check if an agent is halted
+     */
+    isAgentHalted(agentId: string): boolean;
+    /**
+     * Check if the entire fleet is halted
+     */
+    isFleetHalted(): boolean;
+    /**
+     * Add a human-defined policy
+     */
+    addPolicy(policy: AuditPolicy): void;
+    /**
+     * Remove a policy
+     */
+    removePolicy(policyId: string, removedBy: string): void;
+    /**
+     * Get all active policies
+     */
+    getPolicies(): AuditPolicy[];
+    /**
+     * Query audit entries
+     */
+    query(filter: AuditFilter): Promise<AuditEntry[]>;
+    /**
+     * Get all alerts
+     */
+    getAlerts(unacknowledgedOnly?: boolean): AuditAlert[];
+    /**
+     * Acknowledge an alert
+     */
+    acknowledgeAlert(alertId: string, acknowledgedBy: string): boolean;
+    /**
+     * Get status of all tracked agents
+     */
+    getAgentStatuses(): AuditAgentStatus[];
+    /**
+     * Get status of a specific agent
+     */
+    getAgentStatus(agentId: string): AuditAgentStatus | undefined;
+    /**
+     * Get total entry count
+     */
+    getTotalEntries(): Promise<number>;
+}
+//# sourceMappingURL=observer.d.ts.map

package/dist/audit/observer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"observer.d.ts","sourceRoot":"","sources":["../../src/audit/observer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,EAAyB,KAAK,YAAY,EAAsB,MAAM,cAAc,CAAA;AAE3F,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAC5C,OAAO,KAAK,EACV,gBAAgB,EAChB,UAAU,EACV,UAAU,EAEV,WAAW,EACX,WAAW,EAEZ,MAAM,YAAY,CAAA;AAInB,MAAM,WAAW,mBAAmB;IAClC,0BAA0B;IAC1B,KAAK,EAAE,UAAU,CAAA;IACjB,uEAAuE;IACvE,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B,0CAA0C;IAC1C,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,CAAA;IACrC,uCAAuC;IACvC,aAAa,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,IAAI,CAAA;IACzD,+CAA+C;IAC/C,aAAa,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAA;CACzC;AAID,qBAAa,aAAa;IACxB,OAAO,CAAC,KAAK,CAAY;IACzB,OAAO,CAAC,YAAY,CAAmB;IACvC,OAAO,CAAC,aAAa,CAAmB;IACxC,OAAO,CAAC,iBAAiB,CAAQ;IACjC,OAAO,CAAC,WAAW,CAA2C;IAC9D,OAAO,CAAC,WAAW,CAAQ;IAC3B,OAAO,CAAC,OAAO,CAAC,CAA6B;IAC7C,OAAO,CAAC,aAAa,CAAC,CAA2C;IACjE,OAAO,CAAC,aAAa,CAAC,CAA0B;gBAEpC,MAAM,EAAE,mBAAmB;IAWvC;;;OAGG;IACH,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,YAAY;YA6BtC,WAAW;IAqEzB;;OAEG;IACH,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI;IA6BlE;;OAEG;IACH,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI;IAoBrD;;OAEG;IACH,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI;IAuBjD;;OAEG;IACH,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAoBpC;;OAEG;IACH,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;IAKvC;;OAEG;IACH,aAAa,IAAI,OAAO;IAMxB;;OAEG;IACH,SAAS,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI;IAepC;;OAEG;IACH,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI;IAcvD;;OAEG;IACH,WAAW,IAAI,WAAW,EAAE;IAM5B;;OAEG;IACG,KAAK,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;IAIvD;;OAEG;IACH,SAAS,CAAC,kBAAkB,UAAQ,GAAG,UAAU,EAAE;IAInD;;OAEG;IACH,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,OAAO;IAkBlE;;OAEG;IACH,gBAAgB,IAAI,gBAAgB,EAAE;IAItC;;OAEG;IACH,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,gBAAgB,GAAG,SAAS;IAI7D;;OAEG;IACG,eAAe,IAAI,OAAO,CAAC,MAAM,CAAC;CAGzC"}