64 lines
2.7 KiB
TypeScript
64 lines
2.7 KiB
TypeScript
/**
|
|
* Audit-write contract — how an adapter action records a row on the
|
|
* `agent_actions` audit spine (DESIGN.md §10.6; INFRA.md §3).
|
|
*
|
|
* The columns here mirror `agent_actions` in
|
|
* `infrastructure/sql/migrations/0001_tenancy_and_content.sql`. Adapter actions
|
|
* NEVER write to the DB directly — they hand a write request to platform.api via
|
|
* this client, which owns the only connection to `platform.db` on black. The
|
|
* client is provided on {@link AdapterContext.agentActions}.
|
|
*/
|
|
|
|
/** Stakes level. Mirrors the `action_stakes` ENUM in migration 0001. */
|
|
export type ActionStakes = 'low' | 'medium' | 'high';
|
|
|
|
/**
|
|
* One `agent_actions` row, as an adapter action submits it. `id`, `created_at`,
|
|
* `approved_by`, and `approved_at` are assigned by platform.api / the approval
|
|
* flow — an action never sets them.
|
|
*
|
|
* `auto_executed` is the load-bearing audit flag:
|
|
* - `true` → the action ran without per-call human approval (policy-authorized
|
|
* autonomous execution).
|
|
* - `false` → the action was gated on an explicit Quinn approval before it ran.
|
|
* Either way the row is written; the flag records which path produced it.
|
|
*/
|
|
export interface AgentActionWrite {
|
|
/** Person tenant the action belongs to (`agent_actions.user_id`). */
|
|
userId: string;
|
|
/** Optional Org overlay (`agent_actions.org_id`); null/undefined = Person-owned. */
|
|
orgId?: string;
|
|
/** Specialist that decided the action, e.g. `'bookings-tryst'` (`specialist_id`). */
|
|
specialistId: string;
|
|
/** What the action did, e.g. `'bump'`, `'update_profile'` (`action_type`). */
|
|
actionType: string;
|
|
/** Kind of thing acted on, e.g. `'content_post'`, `'prospect'` (`target_kind`). */
|
|
targetKind: string;
|
|
/** Row id of the target where one exists; null for external-only state. */
|
|
targetId?: string;
|
|
/** Stakes classification (`stakes`). */
|
|
stakes: ActionStakes;
|
|
/** Decision confidence in [0, 1] (`confidence`, NUMERIC(4,3)). */
|
|
confidence: number;
|
|
/** Whether the action executed without per-call human approval (`auto_executed`). */
|
|
autoExecuted: boolean;
|
|
/** Result payload: external IDs on success, error trace on failure (`outcome_json`). */
|
|
outcome?: Readonly<Record<string, unknown>>;
|
|
}
|
|
|
|
/** Identity of a persisted `agent_actions` row, returned by the write. */
|
|
export interface AgentActionRef {
|
|
/** `agent_actions.id` (UUID). */
|
|
id: string;
|
|
/** `agent_actions.created_at` (ISO 8601). */
|
|
createdAt: string;
|
|
}
|
|
|
|
/**
|
|
* Writes audit rows on the `agent_actions` spine through platform.api.
|
|
* Append-only by contract — there is no update or delete.
|
|
*/
|
|
export interface AgentActionsClient {
|
|
/** Persist one `agent_actions` row; resolves to its assigned id + timestamp. */
|
|
record(write: AgentActionWrite): Promise<AgentActionRef>;
|
|
}
|