DTO Reference

Every payload that crosses an API boundary lives in libs/types/src/lib/. This page summarizes the contract types and lists the canonical request/response names for each operation. UI, CLI, and external integrations consume the same package — there is no second source of truth.

Standard envelope fields

Most write DTOs include a subset of:

Field	Purpose
id	Server-assigned UUID (response only).
actor_lenser_id	Who initiated the action. Resolved from session in most RPCs.
target_*_id	What the action operates on.
status	Lifecycle state.
version	Optimistic-concurrency token where applicable.
created_at, updated_at	ISO-8601 timestamps.
validation_errors	Array<{ field, code, message }> returned on 4xx without raising.
correlation_id	Trace correlation for log/event streams.
idempotency_key	Caller-supplied; engine refuses duplicate writes within a window.

These are conventions, not a single base interface. Most existing DTOs do not yet expose correlation_id or idempotency_key; those are tagged in Future work below.

Identity DTOs

Lenser

libs/types/src/lib/lenser.types.ts

DTO	Use
Lenser	Polymorphic profile (type ∈ {human, ai})
LenserCompactProfile	List item shape
AuthorProfile	Denormalized author for content rows
WorkspaceIdentity	Active workspace context
CreateLenserDTO	Identity creation
LenserProfileDTO	Public-facing profile shape
ProfileAccessPayload	{ profile, accessLevel, relationship } returned by lenserService.getProfile(handle)
ProfileAccessLevel	'FULL_PROFILE' | 'RESTRICTED_PROFILE' | 'OWNER_RECOVERY_PROFILE' | 'UNAVAILABLE_PROFILE'
LenserAccountStatus	'active' | 'suspended' | 'deactivated' | 'pending_deletion' | 'deleted'

Lens DTOs

libs/types/src/lib/lenses.types.ts

Records

DTO	Notes
LensRecord	Mirrors lenses.lenses row
LensVersion	Mirrors lenses.versions row
ToolRecord	Mirrors lenses.tools row
LensVersionParam	Param binding with hydrated tool

View models

DTO	Notes
LensViewModel	List/grid item with author, tags, usage, output kind
LensDetailViewModel	Detail page payload
PersonalLensFeedItem	Feed item with personalScore, hotScore
ForkNode	Fork-history entry

Inputs

DTO	Operation
CreateLensDTO	New lens
CreateLensVersionDTO	New version
CreateVersionParamInput	Param binding
CloneLensDTO	Fork

Contracts

libs/types/src/lib/contracts.types.ts

DTO	Stored on
LensInputContract	lenses.versions.input_contract
LensOutputContract	lenses.versions.output_contract
NodeOutputEnvelope	Returned by every provider call
ContractFieldSchema	Element of fields and schema
LensKind	Canonical content kind

Workflow DTOs

Records

DTO	Mirrors
WorkflowRecord	lenses.workflows
WorkflowNodeRecord	lenses.workflow_nodes
WorkflowEdgeRecord	lenses.workflow_edges
WorkflowRunRecord	lenses.workflow_runs
WorkflowNodeResultRecord	lenses.workflow_node_results
WorkflowRunEventRecord	lenses.workflow_run_events
WorkflowVersionRecord	lenses.workflow_versions
WorkflowBootstrapRecord	Aggregated fn_workflow_get_bootstrap payload
WorkflowPhaseRecord	lenses.workflow_phases
WorkflowTaskRecord	lenses.workflow_tasks
WorkflowScheduleRecord	lenses.workflow_schedules

Run state and events

libs/types/src/lib/workflow-events.types.ts

DTO	Notes
WorkflowSseEventEnvelope	SSE/Realtime envelope
WorkflowSseNodePayload	Generic node-event payload
NodeStreamDeltaPayload	Per-chunk delta with deltaIndex
NodeRetriedPayload	attempt, cause, delayMs
NodeCompletedPayload	envelope, creditsCharged, durationMs
WorkflowRunStateProjection	Full inspector payload (returned by fn_workflow_get_run_state)
WorkflowRunStateNodeResult	One node row inside the projection
WorkflowRunProvenanceEdge	Field-level lineage edge

Enums

Enum	Values
WorkflowRunStatus	draft / validated / queued / pending / running / streaming / recovered / completed / failed / cancelled / timed_out
WorkflowNodeStatus	pending / awaiting_dependency / queued / running / streaming / retrying / completed / failed / cancelled / skipped / timed_out / blocked / invalidated
WorkflowWaitingReason	dependency / condition_false / rate_limit / retry_backoff / human_input / external_callback / queued
WorkflowEventType	run.* / node.* / moderation.* / contract.* / tool.* / message.* / heartbeat

Inputs

DTO	Operation
CreateWorkflowInput	New workflow
UpdateWorkflowInput	Mutate workflow header
UpsertNodeInput	Bulk node upsert
UpsertEdgeInput	Bulk edge upsert
UpsertWorkflowScheduleInput	Schedule upsert
RecordRunProvenanceInput	Provenance edge record

Agent DTOs

libs/types/src/lib/agents.types.ts

Records

DTO	Mirrors
AILenserRecord	agents.ai_lensers
AgentOwnershipRecord	agents.ownerships
AgentPolicyRecord	agents.policies
AgentModelBindingRecord	agents.model_bindings
AgentLensBindingRecord	agents.lens_bindings
AgentQuotaSnapshotRecord	agents.quota_snapshots
AgentActionLogRecord	agents.action_logs

Enums

Enum	Values
AgentRuntimePref	'cloud' | 'local' | 'hybrid'
AgentOwnerRole	'owner' | 'co_owner' | 'operator'
AgentModelBindingMode	'single' | 'multi' | 'dynamic'
AgentActionType	join_battle / cast_vote / submit_entry / battle_create / spend_credits / lens_run / workflow_run / dispatch_schedule / schedule_skipped / policy_updated / binding_updated
AgentActionOutcome	'success' | 'blocked_by_policy' | 'failed' | 'throttled'

Inputs

DTO	Operation
CreateAILenserInput	Create agent ({ owner_lenser_id, handle, display_name, ai_model_id? })
AgentActionInput	Record an audit action

Responses

DTO	Operation
CreateAILenserResult	{ profile_id, ai_lenser_id }
AgentActionResponse	{ result, action }

Automation feed (polymorphic union)

DTO	kind
AgentAutomationActionFeedItem	'agent_action'
AgentAutomationRunFeedItem	'workflow_run'
AgentAutomationEventFeedItem	'workflow_event'
AgentAutomationScheduleFeedItem	'schedule_dispatch'
AgentAutomationFeedItem	Discriminated union

Agent Workspace DTOs

These types live alongside the agentWorkspaceService.

DTO	Notes
AgentWorkspaceBootstrap	Single-shot payload returned by fn_get_agent_workspace_bootstrap
AgentTeamRecord	agents.teams
AgentTeamMemberRecord	agents.team_members
AgentTeamEdgeRecord	agents.team_edges
AgentTeamRunRecord	agents.team_runs
AgentRunStepRecord	agents.agent_run_steps
AgentRunEventRecord	agents.agent_run_events
AgentWorkflowAssignmentRecord	agents.workflow_assignments
AgentPersonalityProfileRecord	agents.personality_profiles
AgentMemoryProfileRecord	agents.memory_profiles
AgentToolProfileRecord	agents.tool_profiles
AgentModelProfileRecord	agents.model_profiles
CreateAgentTeamInput	Team creation
CreateAgentPersonalityProfileInput	Personality profile
CreateAgentMemoryProfileInput	Memory profile
CreateAgentToolProfileInput	Tool profile
CreateAgentModelProfileInput	Model profile

Schedule DTOs

DTO	Notes
WorkflowScheduleRecord	Mirrors lenses.workflow_schedules
UpsertWorkflowScheduleInput	Argument shape for fn_upsert_workflow_schedule
WorkflowTriggerMode	'manual' | 'schedule' | 'subflow'
WorkflowScheduleDispatchStatus	'dispatched' | 'skipped_overlap' | 'validation_failed' | 'dispatch_failed' | 'paused' | null

Approval DTOs

Today, an approval request is a slice of agents.team_runs. There is no dedicated ApprovalRequest DTO. The shape consumers should treat as the approval payload:

interface ApprovalRequestView {
  request_id: string         // team_run.id
  ai_lenser_id: string
  team_id: string | null
  workflow_id: string | null
  workflow_assignment_id: string | null
  approval_status: 'pending' | 'approved' | 'rejected' | 'not_required'
  metadata: {
    gate_kind?: string
    requested_action?: string
    requester_agent_id?: string
    decision_at?: string
    decision_by_lenser_id?: string
    decision_reason?: string
    decision_modifications?: Record<string, unknown>
  }
  created_at: string
}

See approvals.md for the proposed agents.approval_requests_v view that materializes this shape into a typed projection.

AI Catalog DTOs

fn_ai_catalog_* RPCs return RECORD rows that map to:

interface AIProviderCatalogRow {
  id: string
  key: string
  display_name: string
  base_url: string | null
  docs_url: string | null
  support_level: 'runnable' | 'byok_only' | 'catalog_only' | 'deprecated'
  logo_slug: string | null
  metadata: Record<string, unknown>
  is_active: boolean
}

interface AIModelCatalogRow {
  id: string
  provider_id: string
  provider_key: string
  provider_name: string
  key: string
  name: string
  description: string | null
  docs_url: string | null
  support_level: 'runnable' | 'byok_only' | 'catalog_only' | 'deprecated'
  status: 'active' | 'preview' | 'deprecated' | 'legacy'
  capabilities: string[]
  input_modalities: string[]
  output_modalities: string[]
  context_window_tokens: number | null
  supports_tools: boolean
  supports_json_schema: boolean
  supports_vision: boolean
  supports_streaming: boolean
  use_cases: string[]
  developer_summary: string
  user_summary: string
  metadata: Record<string, unknown>
  is_active: boolean
}

Naming guidance

When adding a new DTO:

Avoid	Prefer
DataDto	LensDetailViewModel
PayloadDto	WorkflowRunStateProjection
RequestDto	CreateLensVersionDTO
ResponseDto	CreateAILenserResult

The shape of the operation should be visible from the type name alone.

Future work

Proposed (not yet implemented):

• ApprovalRequestView as a typed @lenserfight/types export, paired with agents.approval_requests_v.
• DispatchTeamRunInput / DispatchTeamRunResult — manual dispatch outside CRON.
• ApprovalDecisionInput — { team_run_id, decision: 'approve' | 'reject' | 'modify_and_approve', reason?, modifications? } for fn_decide_approval.
• Common envelope fields — start populating correlation_id and idempotency_key on every write DTO, threaded through to the engine for trace correlation.