recoder-a2a-sdk 1.0.0

package/dist/audit-helpers.d.mts

@@ -0,0 +1,209 @@
+import { AuditEvent } from '@recoder/shared/a2a/schemas';
+import { RecoderAgentPlatform } from '@recoder/shared/a2a';
+
+/**
+ * @module audit-helpers
+ *
+ * High-level audit event emitter helpers for common A2A operations.
+ *
+ * Instead of manually constructing `CreateAuditEventInput` objects for every
+ * lifecycle event, adapter code can call these type-safe helper functions
+ * which pre-fill the `event_type`, `actor`, `target`, and `severity` fields
+ * for the most common scenarios.
+ *
+ * All helpers return an `AuditEvent` (not a side-effecting "emit"). The
+ * caller is responsible for persisting or publishing the event through
+ * the audit-log service transport layer.
+ *
+ * @example
+ * ```ts
+ * import { emitTaskSubmitted, emitConnectorInvoked } from '@recoder/a2a-sdk/audit-helpers';
+ *
+ * const evt = emitTaskSubmitted({
+ *   id: 'evt_01',
+ *   task_id: 'task_01',
+ *   workspace_id: 'ws_abc',
+ *   trace_id: '4bf92f3577b34da6a3ce929d0e0e4736',
+ *   actor_agent_id: 'agent-pm',
+ *   actor_platform: 'recoder_pm',
+ * });
+ * await auditLogService.persist(evt);
+ * ```
+ */
+
+/**
+ * Common fields required by all audit event helpers.
+ */
+interface AuditEventBase {
+    /** Unique event ID. */
+    id: string;
+    /** Workspace ID. */
+    workspace_id: string;
+    /** Trace ID for correlation with the originating TaskEnvelope. */
+    trace_id: string;
+    /** Optional thread ID. */
+    thread_id?: string;
+    /** Optional parent event ID. */
+    parent_event_id?: string;
+    /** Optional additional metadata. */
+    metadata?: Record<string, unknown>;
+    /** Optional tags. */
+    tags?: string[];
+    /** Override the timestamp (defaults to now). */
+    now?: string;
+}
+/**
+ * Fields for task-scoped audit events.
+ */
+interface TaskAuditEventInput extends AuditEventBase {
+    /** The task ID that this event is about. */
+    task_id: string;
+    /** The actor agent ID. */
+    actor_agent_id: string;
+    /** The actor's platform. */
+    actor_platform: RecoderAgentPlatform;
+    /** Optional actor display name. */
+    actor_name?: string;
+}
+/**
+ * Fields for connector-scoped audit events.
+ */
+interface ConnectorAuditEventInput extends AuditEventBase {
+    /** The connector ID. */
+    connector_id: string;
+    /** The connector platform. */
+    connector_platform: RecoderAgentPlatform;
+    /** Optional task ID. */
+    task_id?: string;
+    /** Optional connector display name. */
+    connector_name?: string;
+}
+/**
+ * Emit a `task.submitted` audit event.
+ *
+ * Call this when a new task envelope is created and submitted to the
+ * control plane.
+ */
+declare function emitTaskSubmitted(input: TaskAuditEventInput): AuditEvent;
+/**
+ * Emit a `task.started` audit event.
+ *
+ * Call this when a task transitions from `submitted` to `working`.
+ */
+declare function emitTaskStarted(input: TaskAuditEventInput): AuditEvent;
+/**
+ * Emit a `task.progress` audit event.
+ *
+ * Call this for intermediate progress updates during task execution.
+ */
+declare function emitTaskProgress(input: TaskAuditEventInput & {
+    progress_pct?: number;
+}): AuditEvent;
+/**
+ * Emit a `task.input_required` audit event.
+ *
+ * Call this when the assignee agent needs additional input.
+ */
+declare function emitTaskInputRequired(input: TaskAuditEventInput): AuditEvent;
+/**
+ * Emit a `task.completed` audit event.
+ *
+ * Call this when a task reaches the `completed` terminal state.
+ */
+declare function emitTaskCompleted(input: TaskAuditEventInput & {
+    duration_ms?: number;
+}): AuditEvent;
+/**
+ * Emit a `task.failed` audit event.
+ *
+ * Call this when a task reaches the `failed` terminal state.
+ */
+declare function emitTaskFailed(input: TaskAuditEventInput & {
+    error_code?: string;
+    error_message?: string;
+    duration_ms?: number;
+}): AuditEvent;
+/**
+ * Emit a `task.cancelled` audit event.
+ *
+ * Call this when a task is explicitly cancelled.
+ */
+declare function emitTaskCancelled(input: TaskAuditEventInput & {
+    reason?: string;
+}): AuditEvent;
+/**
+ * Emit a `connector.attached` audit event.
+ *
+ * Call this when a connector is attached to an agent for task execution.
+ */
+declare function emitConnectorAttached(input: ConnectorAuditEventInput): AuditEvent;
+/**
+ * Emit a `connector.health` audit event.
+ *
+ * Call this when a connector emits a health check or diagnostic event.
+ */
+declare function emitConnectorHealth(input: ConnectorAuditEventInput & {
+    healthy: boolean;
+    latency_ms?: number;
+}): AuditEvent;
+/**
+ * Emit a `connector.error` audit event.
+ *
+ * Call this when a connector encounters an error during task execution.
+ */
+declare function emitConnectorError(input: ConnectorAuditEventInput & {
+    error_code?: string;
+    error_message: string;
+}): AuditEvent;
+/**
+ * Input for policy audit events.
+ */
+interface PolicyAuditEventInput extends AuditEventBase {
+    /** The task ID the policy was checked for. */
+    task_id: string;
+    /** The agent ID the policy was evaluated against. */
+    agent_id: string;
+    /** The policy action (e.g. 'file:write', 'bash:exec'). */
+    action: string;
+    /** The rule that was applied ('auto', 'prompt', 'deny'). */
+    rule: string;
+    /** Whether the action was approved. */
+    approved: boolean;
+    /** Human-readable reason for the decision. */
+    reason: string;
+    /** Duration of the policy check. */
+    duration_ms?: number;
+}
+/**
+ * Emit a `policy.checked` audit event.
+ *
+ * Call this after a policy evaluation completes.
+ */
+declare function emitPolicyChecked(input: PolicyAuditEventInput): AuditEvent;
+/**
+ * Emit a `policy.approved` audit event.
+ *
+ * Convenience wrapper around `emitPolicyChecked` for approved actions.
+ */
+declare function emitPolicyApproved(input: Omit<PolicyAuditEventInput, 'approved'>): AuditEvent;
+/**
+ * Emit a `policy.denied` audit event.
+ *
+ * Convenience wrapper for denied actions.
+ */
+declare function emitPolicyDenied(input: Omit<PolicyAuditEventInput, 'approved'>): AuditEvent;
+/**
+ * Automatically emit the correct audit event type for a task state
+ * transition. This is the preferred method for adapter code that processes
+ * state changes and wants to emit a matching audit event without manually
+ * switching on the state.
+ *
+ * @param input - The task audit event input.
+ * @param newState - The canonical state the task transitioned to.
+ * @returns An `AuditEvent` with the correct event_type for the transition.
+ */
+declare function emitAuditForTransition(input: TaskAuditEventInput & {
+    duration_ms?: number;
+}, newState: string): AuditEvent;
+
+export { type AuditEventBase, type ConnectorAuditEventInput, type PolicyAuditEventInput, type TaskAuditEventInput, emitAuditForTransition, emitConnectorAttached, emitConnectorError, emitConnectorHealth, emitPolicyApproved, emitPolicyChecked, emitPolicyDenied, emitTaskCancelled, emitTaskCompleted, emitTaskFailed, emitTaskInputRequired, emitTaskProgress, emitTaskStarted, emitTaskSubmitted };

package/dist/audit-helpers.d.ts

@@ -0,0 +1,209 @@
+import { AuditEvent } from '@recoder/shared/a2a/schemas';
+import { RecoderAgentPlatform } from '@recoder/shared/a2a';
+
+/**
+ * @module audit-helpers
+ *
+ * High-level audit event emitter helpers for common A2A operations.
+ *
+ * Instead of manually constructing `CreateAuditEventInput` objects for every
+ * lifecycle event, adapter code can call these type-safe helper functions
+ * which pre-fill the `event_type`, `actor`, `target`, and `severity` fields
+ * for the most common scenarios.
+ *
+ * All helpers return an `AuditEvent` (not a side-effecting "emit"). The
+ * caller is responsible for persisting or publishing the event through
+ * the audit-log service transport layer.
+ *
+ * @example
+ * ```ts
+ * import { emitTaskSubmitted, emitConnectorInvoked } from '@recoder/a2a-sdk/audit-helpers';
+ *
+ * const evt = emitTaskSubmitted({
+ *   id: 'evt_01',
+ *   task_id: 'task_01',
+ *   workspace_id: 'ws_abc',
+ *   trace_id: '4bf92f3577b34da6a3ce929d0e0e4736',
+ *   actor_agent_id: 'agent-pm',
+ *   actor_platform: 'recoder_pm',
+ * });
+ * await auditLogService.persist(evt);
+ * ```
+ */
+
+/**
+ * Common fields required by all audit event helpers.
+ */
+interface AuditEventBase {
+    /** Unique event ID. */
+    id: string;
+    /** Workspace ID. */
+    workspace_id: string;
+    /** Trace ID for correlation with the originating TaskEnvelope. */
+    trace_id: string;
+    /** Optional thread ID. */
+    thread_id?: string;
+    /** Optional parent event ID. */
+    parent_event_id?: string;
+    /** Optional additional metadata. */
+    metadata?: Record<string, unknown>;
+    /** Optional tags. */
+    tags?: string[];
+    /** Override the timestamp (defaults to now). */
+    now?: string;
+}
+/**
+ * Fields for task-scoped audit events.
+ */
+interface TaskAuditEventInput extends AuditEventBase {
+    /** The task ID that this event is about. */
+    task_id: string;
+    /** The actor agent ID. */
+    actor_agent_id: string;
+    /** The actor's platform. */
+    actor_platform: RecoderAgentPlatform;
+    /** Optional actor display name. */
+    actor_name?: string;
+}
+/**
+ * Fields for connector-scoped audit events.
+ */
+interface ConnectorAuditEventInput extends AuditEventBase {
+    /** The connector ID. */
+    connector_id: string;
+    /** The connector platform. */
+    connector_platform: RecoderAgentPlatform;
+    /** Optional task ID. */
+    task_id?: string;
+    /** Optional connector display name. */
+    connector_name?: string;
+}
+/**
+ * Emit a `task.submitted` audit event.
+ *
+ * Call this when a new task envelope is created and submitted to the
+ * control plane.
+ */
+declare function emitTaskSubmitted(input: TaskAuditEventInput): AuditEvent;
+/**
+ * Emit a `task.started` audit event.
+ *
+ * Call this when a task transitions from `submitted` to `working`.
+ */
+declare function emitTaskStarted(input: TaskAuditEventInput): AuditEvent;
+/**
+ * Emit a `task.progress` audit event.
+ *
+ * Call this for intermediate progress updates during task execution.
+ */
+declare function emitTaskProgress(input: TaskAuditEventInput & {
+    progress_pct?: number;
+}): AuditEvent;
+/**
+ * Emit a `task.input_required` audit event.
+ *
+ * Call this when the assignee agent needs additional input.
+ */
+declare function emitTaskInputRequired(input: TaskAuditEventInput): AuditEvent;
+/**
+ * Emit a `task.completed` audit event.
+ *
+ * Call this when a task reaches the `completed` terminal state.
+ */
+declare function emitTaskCompleted(input: TaskAuditEventInput & {
+    duration_ms?: number;
+}): AuditEvent;
+/**
+ * Emit a `task.failed` audit event.
+ *
+ * Call this when a task reaches the `failed` terminal state.
+ */
+declare function emitTaskFailed(input: TaskAuditEventInput & {
+    error_code?: string;
+    error_message?: string;
+    duration_ms?: number;
+}): AuditEvent;
+/**
+ * Emit a `task.cancelled` audit event.
+ *
+ * Call this when a task is explicitly cancelled.
+ */
+declare function emitTaskCancelled(input: TaskAuditEventInput & {
+    reason?: string;
+}): AuditEvent;
+/**
+ * Emit a `connector.attached` audit event.
+ *
+ * Call this when a connector is attached to an agent for task execution.
+ */
+declare function emitConnectorAttached(input: ConnectorAuditEventInput): AuditEvent;
+/**
+ * Emit a `connector.health` audit event.
+ *
+ * Call this when a connector emits a health check or diagnostic event.
+ */
+declare function emitConnectorHealth(input: ConnectorAuditEventInput & {
+    healthy: boolean;
+    latency_ms?: number;
+}): AuditEvent;
+/**
+ * Emit a `connector.error` audit event.
+ *
+ * Call this when a connector encounters an error during task execution.
+ */
+declare function emitConnectorError(input: ConnectorAuditEventInput & {
+    error_code?: string;
+    error_message: string;
+}): AuditEvent;
+/**
+ * Input for policy audit events.
+ */
+interface PolicyAuditEventInput extends AuditEventBase {
+    /** The task ID the policy was checked for. */
+    task_id: string;
+    /** The agent ID the policy was evaluated against. */
+    agent_id: string;
+    /** The policy action (e.g. 'file:write', 'bash:exec'). */
+    action: string;
+    /** The rule that was applied ('auto', 'prompt', 'deny'). */
+    rule: string;
+    /** Whether the action was approved. */
+    approved: boolean;
+    /** Human-readable reason for the decision. */
+    reason: string;
+    /** Duration of the policy check. */
+    duration_ms?: number;
+}
+/**
+ * Emit a `policy.checked` audit event.
+ *
+ * Call this after a policy evaluation completes.
+ */
+declare function emitPolicyChecked(input: PolicyAuditEventInput): AuditEvent;
+/**
+ * Emit a `policy.approved` audit event.
+ *
+ * Convenience wrapper around `emitPolicyChecked` for approved actions.
+ */
+declare function emitPolicyApproved(input: Omit<PolicyAuditEventInput, 'approved'>): AuditEvent;
+/**
+ * Emit a `policy.denied` audit event.
+ *
+ * Convenience wrapper for denied actions.
+ */
+declare function emitPolicyDenied(input: Omit<PolicyAuditEventInput, 'approved'>): AuditEvent;
+/**
+ * Automatically emit the correct audit event type for a task state
+ * transition. This is the preferred method for adapter code that processes
+ * state changes and wants to emit a matching audit event without manually
+ * switching on the state.
+ *
+ * @param input - The task audit event input.
+ * @param newState - The canonical state the task transitioned to.
+ * @returns An `AuditEvent` with the correct event_type for the transition.
+ */
+declare function emitAuditForTransition(input: TaskAuditEventInput & {
+    duration_ms?: number;
+}, newState: string): AuditEvent;
+
+export { type AuditEventBase, type ConnectorAuditEventInput, type PolicyAuditEventInput, type TaskAuditEventInput, emitAuditForTransition, emitConnectorAttached, emitConnectorError, emitConnectorHealth, emitPolicyApproved, emitPolicyChecked, emitPolicyDenied, emitTaskCancelled, emitTaskCompleted, emitTaskFailed, emitTaskInputRequired, emitTaskProgress, emitTaskStarted, emitTaskSubmitted };