kandev/apps/backend/internal/task/models/interactions.go

package models

import "time"

// InteractionKind names the two agent-initiated request kinds that block a
// turn on a human decision. It is the durable vocabulary behind the compact
// TaskPendingAction projection, kept as its own type because the interaction
// contract carries the full request (options, questions, resolution) rather
// than the one-word "what is this session waiting on" answer.
type InteractionKind string

const (
	// InteractionKindPermission is a tool-permission request (ACP
	// session/request_permission), persisted as a permission_request message.
	InteractionKindPermission InteractionKind = "permission"
	// InteractionKindClarification is a structured question bundle
	// (ask_user_question), persisted as one clarification_request message per
	// question, all sharing metadata.pending_id.
	InteractionKindClarification InteractionKind = "clarification"
)

// InteractionStatus is the normalized resolution state of an interaction. It
// unifies PermissionStatus (approved/rejected/expired) with the clarification
// vocabulary (answered/rejected/cancelled/expired) so a consumer can branch on
// "still owed a response" without knowing which kind it is holding.
//
// Both kinds record the unresolved state differently on disk — a permission
// message omits metadata.status entirely, a clarification writes "pending" —
// so readers must normalize through InteractionStatusFromMetadata rather than
// comparing the raw metadata value.
type InteractionStatus string

const (
	// InteractionStatusPending means the interaction is still owed a response.
	InteractionStatusPending InteractionStatus = "pending"
	// InteractionStatusApproved is a permission the user accepted.
	InteractionStatusApproved InteractionStatus = "approved"
	// InteractionStatusRejected is a permission the user denied or a
	// clarification bundle the user declined.
	InteractionStatusRejected InteractionStatus = "rejected"
	// InteractionStatusAnswered is a clarification bundle the user answered.
	InteractionStatusAnswered InteractionStatus = "answered"
	// InteractionStatusCancelled is a clarification withdrawn by the operator.
	InteractionStatusCancelled InteractionStatus = "cancelled"
	// InteractionStatusExpired means the request became unanswerable before a
	// response arrived (the agent withdrew it, or its pending entry was gone).
	InteractionStatusExpired InteractionStatus = "expired"
)

// metadataStatusPending is the literal a clarification message writes for the
// unresolved state. A permission message writes nothing at all (see
// PermissionStatusPending), so both the empty string and this literal
// normalize to InteractionStatusPending.
const metadataStatusPending = "pending"

// IsTerminal reports whether the interaction can no longer accept a response.
func (s InteractionStatus) IsTerminal() bool {
	return s != "" && s != InteractionStatusPending
}

// InteractionStatusFromMetadata normalizes a message's metadata.status into an
// InteractionStatus. An absent or empty value is pending, matching
// PermissionStatusPending's absence sentinel. An unrecognized value is
// preserved verbatim rather than coerced to pending: an unknown terminal state
// must never read as "still owed a response".
func InteractionStatusFromMetadata(metadata map[string]interface{}) InteractionStatus {
	raw, _ := metadata["status"].(string)
	if raw == "" || raw == metadataStatusPending {
		return InteractionStatusPending
	}
	return InteractionStatus(raw)
}

// PendingInteractionFilter narrows the durable pending-interaction read.
// SessionIDs and TaskIDs are ORed within each axis and ANDed across the two
// (matching PluginMessageFilter); an empty axis is unconstrained. Kinds
// narrows by InteractionKind; an empty slice means both kinds.
type PendingInteractionFilter struct {
	SessionIDs []string
	TaskIDs    []string
	Kinds      []string
}

// InteractionOption is one selectable response on a permission request or a
// clarification question. Kind carries the ACP permission-option kind
// (allow_once / allow_always / reject_once / reject_always) for permissions and
// is empty for clarification options; Description is the reverse.
type InteractionOption struct {
	ID          string `json:"option_id"`
	Label       string `json:"label"`
	Kind        string `json:"kind,omitempty"`
	Description string `json:"description,omitempty"`
}

// InteractionQuestion is one question of a clarification bundle. Every question
// in a bundle must be answered before the agent unblocks.
type InteractionQuestion struct {
	ID      string              `json:"id"`
	Title   string              `json:"title,omitempty"`
	Prompt  string              `json:"prompt"`
	Options []InteractionOption `json:"options,omitempty"`
}

// Interaction is the assembled durable projection of one agent interaction: a
// permission request, or a whole clarification bundle collapsed from its
// per-question messages. ID is the pending_id the response paths key on.
//
// AgentDisconnected marks a still-pending clarification whose original waiter
// has gone away (the agent moved on or the backend restarted). It stays
// pending and answerable — the answer resumes the session in a new turn — so a
// consumer must not treat disconnection as resolution.
type Interaction struct {
	ID        string            `json:"id"`
	Kind      InteractionKind   `json:"kind"`
	TaskID    string            `json:"task_id"`
	SessionID string            `json:"session_id"`
	TurnID    string            `json:"turn_id"`
	Status    InteractionStatus `json:"status"`
	// RequestID is the provider-side permission request identity. Kandev's
	// resolution path is keyed on it alongside the pending id; empty for a
	// clarification bundle and for permission rows written before it existed.
	RequestID         string                `json:"request_id,omitempty"`
	Title             string                `json:"title,omitempty"`
	Context           string                `json:"context,omitempty"`
	ToolCallID        string                `json:"tool_call_id,omitempty"`
	ActionType        string                `json:"action_type,omitempty"`
	Options           []InteractionOption   `json:"options,omitempty"`
	Questions         []InteractionQuestion `json:"questions,omitempty"`
	AgentDisconnected bool                  `json:"agent_disconnected,omitempty"`
	CreatedAt         time.Time             `json:"created_at"`
	UpdatedAt         time.Time             `json:"updated_at"`
}