ciris-agent 1.7.7__py3-none-any.whl

ciris_engine/schemas/runtime/manifest.py

@@ -0,0 +1,311 @@
+"""
+Service manifest schemas for typed module loading.
+
+Provides typed schemas in service loading and module manifests.
+"""
+
+from datetime import datetime, timezone
+from enum import Enum
+from typing import Any, Dict, List, Literal, Optional, Union
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from ciris_engine.schemas.runtime.enums import ServiceType
+from ciris_engine.schemas.types import JSONDict
+
+
+class ServicePriority(str, Enum):
+    """Service priority levels for registration."""
+
+    CRITICAL = "CRITICAL"
+    HIGH = "HIGH"
+    NORMAL = "NORMAL"
+    LOW = "LOW"
+
+
+class ServiceCapabilityDeclaration(BaseModel):
+    """Declaration of a service capability."""
+
+    name: str = Field(..., description="Capability name (e.g., 'call_llm_structured')")
+    description: str = Field(..., description="Human-readable description of the capability")
+    version: str = Field(default="1.0.0", description="Capability version")
+    parameters: Optional[Dict[str, str]] = Field(None, description="Parameter descriptions")
+
+    model_config = ConfigDict(extra="forbid")
+
+
+class ServiceDependency(BaseModel):
+    """Declaration of a service dependency."""
+
+    service_type: ServiceType = Field(..., description="Type of service required")
+    required: bool = Field(True, description="Whether this dependency is required")
+    minimum_version: Optional[str] = Field(None, description="Minimum service version required")
+    capabilities_required: List[str] = Field(default_factory=list, description="Required capabilities")
+
+    model_config = ConfigDict(extra="forbid")
+
+
+class ServiceDeclaration(BaseModel):
+    """Declaration of a service in a manifest."""
+
+    type: ServiceType = Field(..., description="Service type this implements")
+    class_path: str = Field(..., description="Full class path (e.g., 'mock_llm.service.MockLLMService')", alias="class")
+    priority: ServicePriority = Field(ServicePriority.NORMAL, description="Service priority level")
+    capabilities: List[str] = Field(default_factory=list, description="List of capability names")
+
+    model_config = ConfigDict(extra="forbid", populate_by_name=True)
+
+
+class ModuleInfo(BaseModel):
+    """Module-level information."""
+
+    name: str = Field(..., description="Module name")
+    version: str = Field(..., description="Module version")
+    description: str = Field(..., description="Module description")
+    author: str = Field(..., description="Module author")
+    is_mock: bool = Field(False, description="Whether this is a MOCK module", alias="MOCK")
+    license: Optional[str] = Field(None, description="Module license")
+    homepage: Optional[str] = Field(None, description="Module homepage URL")
+    safe_domain: Optional[bool] = Field(None, description="Whether module operates in safe domains")
+    reference: bool = Field(False, description="Whether this is a reference/example module")
+    for_qa: bool = Field(False, description="Whether this module is for QA/testing")
+
+    model_config = ConfigDict(extra="forbid", populate_by_name=True)
+
+
+class LegacyDependencies(BaseModel):
+    """Legacy dependency format for backward compatibility."""
+
+    protocols: List[str] = Field(default_factory=list, description="Required protocols")
+    schemas: List[str] = Field(default_factory=list, description="Required schemas")
+    external: Optional[Dict[str, str]] = Field(None, description="External package dependencies")
+    internal: Optional[List[str]] = Field(None, description="Internal module dependencies")
+
+    model_config = ConfigDict(extra="forbid")
+
+
+class ConfigurationParameter(BaseModel):
+    """Configuration parameter definition."""
+
+    type: str = Field(..., description="Parameter type (integer, float, string, boolean, array)")
+    default: Optional[Union[int, float, str, bool, List[str]]] = Field(None, description="Default value (optional)")
+    description: str = Field(..., description="Parameter description")
+    env: Optional[str] = Field(None, description="Environment variable name")
+    sensitivity: Optional[str] = Field(None, description="Sensitivity level (e.g., 'HIGH' for secrets)")
+    required: bool = Field(True, description="Whether this parameter is required")
+    enum: Optional[List[str]] = Field(None, description="Allowed values for string parameters")
+
+    model_config = ConfigDict(extra="forbid")
+
+
+class AdapterOAuthConfig(BaseModel):
+    """OAuth configuration for adapter authentication workflows.
+
+    This is distinct from OAuthConfig in wise_authority, which handles full
+    OAuth provider configuration. This schema is for adapter configuration
+    workflows that need OAuth authentication.
+    """
+
+    provider_name: str = Field(..., description="OAuth provider name")
+    authorization_path: str = Field("/auth/authorize", description="OAuth authorization endpoint path")
+    token_path: str = Field("/auth/token", description="OAuth token endpoint path")
+    client_id_source: Literal["static", "indieauth"] = Field(
+        "indieauth", description="Source of client ID (static value or IndieAuth discovery)"
+    )
+    scopes: List[str] = Field(default_factory=list, description="OAuth scopes to request")
+    pkce_required: bool = Field(True, description="Whether PKCE is required for this OAuth flow")
+
+    model_config = ConfigDict(extra="forbid")
+
+
+class ConfigurationFieldDefinition(BaseModel):
+    """Definition of a field within an input step."""
+
+    # Field identification - supports both 'name' and 'field_id' patterns
+    name: Optional[str] = Field(None, description="Field name (alternative to field_id)")
+    field_id: Optional[str] = Field(None, description="Field identifier (alternative to name)")
+    label: Optional[str] = Field(None, description="Human-readable label for the field")
+
+    # Field type and input
+    type: Optional[str] = Field(None, description="Field data type (string, integer, number, boolean, password)")
+    input_type: Optional[str] = Field(None, description="Input control type (text, password, number, select)")
+
+    # Field metadata
+    description: Optional[str] = Field(None, description="Description of the field")
+    placeholder: Optional[str] = Field(None, description="Placeholder text for input")
+    default: Optional[Any] = Field(None, description="Default value")
+    required: bool = Field(False, description="Whether this field is required")
+
+    # Validation
+    min: Optional[Union[int, float]] = Field(None, description="Minimum value")
+    max: Optional[Union[int, float]] = Field(None, description="Maximum value")
+
+    # Conditional display
+    depends_on: Optional[Dict[str, Any]] = Field(None, description="Conditional display based on other fields")
+
+    model_config = ConfigDict(extra="allow")  # Allow additional field-specific properties
+
+
+class ConfigurationStep(BaseModel):
+    """A step in an adapter configuration workflow."""
+
+    step_id: str = Field(..., description="Unique identifier for this step")
+    step_type: Literal["discovery", "oauth", "select", "input", "confirm"] = Field(
+        ..., description="Type of configuration step"
+    )
+    title: str = Field(..., description="Human-readable step title")
+    description: str = Field(..., description="Description of what this step does")
+
+    # Discovery step fields
+    discovery_method: Optional[str] = Field(
+        None, description="Discovery method name (e.g., 'mdns', 'api_scan') for discovery steps"
+    )
+
+    # OAuth step fields
+    oauth_config: Optional[AdapterOAuthConfig] = Field(None, description="OAuth configuration for oauth steps")
+
+    # Select step fields
+    options_method: Optional[str] = Field(
+        None, description="Method name to call for retrieving options in select steps"
+    )
+    multiple: bool = Field(False, description="Whether multiple selections are allowed")
+
+    # Input step fields - complex form with multiple fields
+    fields: Optional[List[ConfigurationFieldDefinition]] = Field(
+        None, description="List of field definitions for input steps"
+    )
+    dynamic_fields: bool = Field(False, description="Whether fields are dynamically generated")
+
+    # Input step fields - simple single field (alternative to 'fields' list)
+    field: Optional[str] = Field(None, description="Single field name (simple input)")
+    field_name: Optional[str] = Field(None, description="Configuration field name for input/select steps")
+    input_type: Optional[str] = Field(None, description="Input type (text, password, number)")
+    placeholder: Optional[str] = Field(None, description="Placeholder text")
+
+    # Step requirements and flow control
+    required: bool = Field(False, description="Whether this step is required")
+    optional: bool = Field(False, description="Whether this step/field is optional")
+    default: Optional[Any] = Field(None, description="Default value for the field")
+    validation: Optional[Dict[str, Any]] = Field(None, description="Validation rules (e.g., min, max, pattern)")
+
+    # Dependencies - supports both list of step_ids and conditional dict
+    depends_on: Optional[Union[List[str], Dict[str, Any]]] = Field(
+        None, description="Step dependencies - list of step_ids or conditional dict"
+    )
+    condition: Optional[Dict[str, Any]] = Field(
+        None, description="Condition for showing this step (e.g., {field: 'x', equals: 'y'})"
+    )
+
+    # Confirm step fields
+    action: Optional[str] = Field(None, description="Action to perform on confirm (e.g., 'test_connection')")
+
+    model_config = ConfigDict(extra="allow")  # Allow additional step-specific properties
+
+
+class InteractiveConfiguration(BaseModel):
+    """Interactive configuration definition for adapters.
+
+    Enables adapters to define multi-step configuration workflows including
+    discovery, OAuth authentication, and user input steps.
+    """
+
+    required: bool = Field(False, description="Whether interactive configuration is required")
+    workflow_type: Literal["wizard", "discovery_then_config", "simple_config"] = Field(
+        "wizard", description="Type of configuration workflow"
+    )
+    steps: List[ConfigurationStep] = Field(default_factory=list, description="Ordered list of configuration steps")
+    completion_method: str = Field("apply_config", description="Method name to call when configuration is complete")
+
+    model_config = ConfigDict(extra="allow")  # Allow reference/documentation fields
+
+
+class ServiceManifest(BaseModel):
+    """Complete service module manifest."""
+
+    module: ModuleInfo = Field(..., description="Module information")
+    services: List[ServiceDeclaration] = Field(default_factory=list, description="Services provided")
+    capabilities: List[str] = Field(default_factory=list, description="Global capabilities list")
+    dependencies: Optional[LegacyDependencies] = Field(None, description="Legacy dependencies format")
+    configuration: Optional[Dict[str, ConfigurationParameter]] = Field(None, description="Configuration parameters")
+    exports: Optional[Dict[str, Union[str, List[str]]]] = Field(
+        None, description="Exported components (string or list)"
+    )
+    metadata: Optional[JSONDict] = Field(None, description="Additional metadata")
+    requirements: List[str] = Field(default_factory=list, description="Python package requirements")
+    prohibited_sensors: Optional[List[str]] = Field(None, description="Prohibited sensor types for sensor modules")
+    prohibited_capabilities: Optional[List[str]] = Field(None, description="Prohibited capabilities for this module")
+    interactive_config: Optional[InteractiveConfiguration] = Field(
+        None, description="Interactive configuration workflow for adapters"
+    )
+
+    model_config = ConfigDict(extra="forbid")
+
+    def validate_manifest(self) -> List[str]:
+        """Validate manifest consistency.
+
+        Returns:
+            List of validation errors (empty if valid)
+        """
+        errors = []
+
+        # Global capabilities are just a list in the current format
+        # Service capabilities can reference these or define their own
+
+        # Check for MOCK module warnings
+        if self.module.is_mock:
+            for service in self.services:
+                if service.priority == ServicePriority.CRITICAL:
+                    # MOCK modules often use CRITICAL priority to override real services
+                    # This is actually allowed but worth noting
+                    pass
+
+        # Validate service types
+        for service in self.services:
+            try:
+                # Ensure service type is valid
+                _ = service.type
+            except Exception as e:
+                errors.append(f"Invalid service type in {service.class_path}: {e}")
+
+        return errors
+
+
+class ServiceMetadata(BaseModel):
+    """Runtime metadata about a loaded service."""
+
+    service_type: ServiceType = Field(..., description="Type of this service")
+    module_name: str = Field(..., description="Module this service came from")
+    class_name: str = Field(..., description="Service class name")
+    version: str = Field(..., description="Service version")
+    is_mock: bool = Field(False, description="Whether this is a MOCK service")
+    loaded_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+    capabilities: List[str] = Field(default_factory=list, description="Active capabilities")
+    priority: ServicePriority = Field(ServicePriority.NORMAL, description="Service priority")
+    health_status: str = Field("unknown", description="Current health status")
+
+    model_config = ConfigDict(extra="forbid")
+
+
+class ModuleLoadResult(BaseModel):
+    """Result of loading a module."""
+
+    module_name: str = Field(..., description="Module that was loaded")
+    success: bool = Field(..., description="Whether load succeeded")
+    services_loaded: List[ServiceMetadata] = Field(default_factory=list, description="Services that were loaded")
+    errors: List[str] = Field(default_factory=list, description="Any errors encountered")
+    warnings: List[str] = Field(default_factory=list, description="Any warnings generated")
+
+    model_config = ConfigDict(extra="forbid")
+
+
+class ServiceRegistration(BaseModel):
+    """Registration information for a service in the registry."""
+
+    service_type: ServiceType = Field(..., description="Type of service")
+    provider_id: str = Field(..., description="Unique ID of the provider instance")
+    priority: ServicePriority = Field(..., description="Registration priority")
+    capabilities: List[str] = Field(default_factory=list, description="Service capabilities")
+    metadata: ServiceMetadata = Field(..., description="Service metadata")
+    registered_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+
+    model_config = ConfigDict(extra="forbid")

ciris_engine/schemas/runtime/memory.py

@@ -0,0 +1,60 @@
+"""
+Memory protocol schemas.
+
+Type-safe schemas for memory service operations.
+"""
+
+from datetime import datetime, timezone
+from typing import Dict, Optional, Union
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class MemorySearchResult(BaseModel):
+    """Result from memory search operation."""
+
+    node_id: str = Field(..., description="Unique identifier of the memory node")
+    content: str = Field(..., description="Memory content")
+    node_type: str = Field(..., description="Type of memory node")
+    relevance_score: float = Field(..., ge=0.0, le=1.0, description="Relevance score (0.0-1.0)")
+    created_at: datetime = Field(..., description="When the memory was created")
+    metadata: Dict[str, str] = Field(default_factory=dict, description="Additional metadata")
+
+    model_config = ConfigDict(extra="forbid")
+
+
+class TimeSeriesDataPoint(BaseModel):
+    """A time-series data point from memory correlations."""
+
+    timestamp: datetime = Field(..., description="Time of the data point")
+    metric_name: str = Field(..., description="Name of the metric")
+    value: float = Field(..., description="Metric value")
+    correlation_type: str = Field(..., description="Type of correlation (e.g., METRIC_DATAPOINT)")
+    tags: Dict[str, str] = Field(default_factory=dict, description="Optional tags")
+    source: Optional[str] = Field(None, description="Source of the data")
+
+    model_config = ConfigDict(extra="forbid")
+
+
+class IdentityUpdateRequest(BaseModel):
+    """Request to update identity graph."""
+
+    node_id: Optional[str] = Field(None, description="Specific node to update")
+    updates: Dict[str, Union[str, int, float, bool]] = Field(..., description="Fields to update")
+    source: str = Field(..., description="Source of the update (e.g., 'wa_feedback')")
+    reason: Optional[str] = Field(None, description="Reason for the update")
+
+    model_config = ConfigDict(extra="forbid")
+
+
+class EnvironmentUpdateRequest(BaseModel):
+    """Request to update environment graph."""
+
+    adapter_type: str = Field(..., description="Type of adapter providing update")
+    environment_data: Dict[str, str] = Field(..., description="Environment data to merge")
+    timestamp: datetime = Field(default_factory=lambda: datetime.now(timezone.utc), description="When update occurred")
+
+    model_config = ConfigDict(extra="forbid")
+
+
+__all__ = ["MemorySearchResult", "TimeSeriesDataPoint", "IdentityUpdateRequest", "EnvironmentUpdateRequest"]

ciris_engine/schemas/runtime/messages.py

@@ -0,0 +1,108 @@
+"""
+Message schemas for CIRIS Trinity Architecture.
+
+Typed message structures for all communication types.
+"""
+
+from enum import Enum
+from typing import TYPE_CHECKING, Any, List, Optional
+
+from pydantic import BaseModel, ConfigDict, Field
+
+if TYPE_CHECKING:
+    from ciris_engine.schemas.runtime.models import ImageContent
+
+
+class MessageHandlingStatus(str, Enum):
+    """Status of message handling after submission."""
+
+    TASK_CREATED = "TASK_CREATED"  # Task successfully created
+    AGENT_OWN_MESSAGE = "AGENT_OWN_MESSAGE"  # Message from agent itself (ignored)
+    FILTERED_OUT = "FILTERED_OUT"  # Filtered by adaptive filter
+    CREDIT_DENIED = "CREDIT_DENIED"  # Insufficient credits
+    CREDIT_CHECK_FAILED = "CREDIT_CHECK_FAILED"  # Credit provider error
+    PROCESSOR_PAUSED = "PROCESSOR_PAUSED"  # Agent processor paused
+    RATE_LIMITED = "RATE_LIMITED"  # Rate limit exceeded
+    CHANNEL_RESTRICTED = "CHANNEL_RESTRICTED"  # Channel access denied
+    UPDATED_EXISTING_TASK = "UPDATED_EXISTING_TASK"  # Flagged existing task with new info
+
+
+class PassiveObservationResult(BaseModel):
+    """Result of creating a passive observation (task + thought)."""
+
+    task_id: str = Field(..., description="Task ID (newly created or existing task that was updated)")
+    task_created: bool = Field(..., description="True if new task created, False if existing task updated")
+    thought_id: Optional[str] = Field(None, description="Thought ID if created")
+    existing_task_updated: bool = Field(default=False, description="Whether an existing task was updated")
+
+
+class MessageHandlingResult(BaseModel):
+    """Result of handling an incoming message through the observer pipeline."""
+
+    status: MessageHandlingStatus = Field(..., description="Status of message handling")
+    task_id: Optional[str] = Field(None, description="Task ID if created or updated")
+    message_id: str = Field(..., description="Original message ID")
+    channel_id: str = Field(..., description="Channel ID where message was sent")
+    filtered: bool = Field(default=False, description="Whether message was filtered out")
+    filter_reasoning: Optional[str] = Field(None, description="Filter reasoning if filtered")
+    credit_denied: bool = Field(default=False, description="Whether denied by credit policy")
+    credit_denial_reason: Optional[str] = Field(None, description="Credit denial reason")
+    task_priority: int = Field(default=0, description="Priority of created task (0=passive, 5=high, 10=critical)")
+    existing_task_updated: bool = Field(default=False, description="Whether an existing task was updated")
+
+
+class IncomingMessage(BaseModel):
+    """Schema for incoming messages from various sources."""
+
+    message_id: str = Field(..., description="Unique message identifier")
+    author_id: str = Field(..., description="Message author ID")
+    author_name: str = Field(..., description="Message author name")
+    content: str = Field(..., description="Message content")
+    destination_id: Optional[str] = Field(default=None, alias="channel_id")
+    reference_message_id: Optional[str] = Field(None, description="ID of message being replied to")
+    timestamp: Optional[str] = Field(None, description="Message timestamp")
+    # Native multimodal support - images attached to the message
+    images: List[Any] = Field(default_factory=list, description="Images attached to this message (List[ImageContent])")
+
+    model_config = ConfigDict(populate_by_name=True, extra="allow")
+
+    @property
+    def channel_id(self) -> Optional[str]:
+        """Backward compatibility alias for destination_id."""
+        return self.destination_id
+
+
+class DiscordMessage(IncomingMessage):
+    """Incoming message specific to the Discord platform."""
+
+    is_bot: bool = Field(default=False, description="Whether author is a bot")
+    is_dm: bool = Field(default=False, description="Whether this is a DM")
+    raw_message: Optional[Any] = Field(default=None, exclude=True)  # Discord.py message object
+
+    def __init__(self, **data: Any) -> None:
+        if "destination_id" not in data and "channel_id" in data:
+            data["destination_id"] = data.get("channel_id")
+        super().__init__(**data)
+
+
+class FetchedMessage(BaseModel):
+    """Message returned by CommunicationService.fetch_messages."""
+
+    message_id: Optional[str] = Field(default=None, alias="id")
+    content: Optional[str] = None
+    author_id: Optional[str] = None
+    author_name: Optional[str] = None
+    timestamp: Optional[str] = None
+    is_bot: Optional[bool] = False
+
+    model_config = ConfigDict(populate_by_name=True, extra="allow")
+
+
+__all__ = [
+    "MessageHandlingStatus",
+    "PassiveObservationResult",
+    "MessageHandlingResult",
+    "IncomingMessage",
+    "DiscordMessage",
+    "FetchedMessage",
+]

ciris_engine/schemas/runtime/models.py

@@ -0,0 +1,156 @@
+"""
+Core models for CIRIS Trinity Architecture.
+
+Task and Thought are the fundamental units of agent processing.
+NO Dict[str, Any] - everything is typed.
+"""
+
+from typing import Any, Dict, List, Literal, Optional
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from ciris_engine.schemas.types import JSONDict
+
+from .enums import TaskStatus, ThoughtStatus, ThoughtType
+
+
+class ImageContent(BaseModel):
+    """
+    Image content for multimodal tasks.
+
+    Supports both base64-encoded images and URLs for native vision processing.
+    Used by adapters to attach images to tasks that flow through the pipeline
+    to DMAs and ultimately to vision-capable LLMs.
+    """
+
+    source_type: Literal["base64", "url"] = Field(..., description="How image is stored")
+    data: str = Field(..., description="Base64 data or URL")
+    media_type: str = Field(default="image/jpeg", description="MIME type: image/jpeg, image/png, image/gif, image/webp")
+    filename: Optional[str] = Field(default=None, description="Original filename if available")
+    size_bytes: Optional[int] = Field(default=None, description="File size in bytes for tracking")
+
+    model_config = ConfigDict(extra="forbid")
+
+    def to_data_url(self) -> str:
+        """Convert to data URL format for LLM APIs."""
+        if self.source_type == "url":
+            return self.data
+        return f"data:{self.media_type};base64,{self.data}"
+
+
+class TaskContext(BaseModel):
+    """Typed context for tasks."""
+
+    channel_id: Optional[str] = Field(None, description="Channel where task originated")
+    user_id: Optional[str] = Field(None, description="User who created task")
+    correlation_id: str = Field(..., description="Correlation ID for tracing")
+    parent_task_id: Optional[str] = Field(None, description="Parent task if nested")
+    agent_occurrence_id: str = Field(default="default", description="Runtime occurrence ID that owns this task")
+
+    model_config = ConfigDict(extra="forbid")
+
+
+class TaskOutcome(BaseModel):
+    """Typed outcome for completed tasks."""
+
+    status: str = Field(..., description="Final status: success, partial, failure")
+    summary: str = Field(..., description="Human-readable summary")
+    actions_taken: List[str] = Field(default_factory=list, description="Actions performed")
+    memories_created: List[str] = Field(default_factory=list, description="Memory node IDs created")
+    errors: List[str] = Field(default_factory=list, description="Errors encountered")
+
+    model_config = ConfigDict(extra="forbid")
+
+
+class ThoughtContext(BaseModel):
+    """Typed context for thoughts."""
+
+    task_id: str = Field(..., description="Parent task ID")
+    channel_id: Optional[str] = Field(None, description="Channel where thought operates")
+    round_number: int = Field(0, description="Processing round")
+    depth: int = Field(0, description="Ponder depth (max 7)")
+    parent_thought_id: Optional[str] = Field(None, description="Parent thought if pondering")
+    correlation_id: str = Field(..., description="Correlation ID")
+    agent_occurrence_id: str = Field(default="default", description="Runtime occurrence ID (inherited from task)")
+
+    model_config = ConfigDict(extra="forbid")
+
+
+class FinalAction(BaseModel):
+    """Typed final action from thought processing."""
+
+    action_type: str = Field(..., description="Action type chosen")
+    action_params: JSONDict = Field(..., description="Action parameters (will be typed per action)")
+    reasoning: str = Field(..., description="Why this action was chosen")
+
+    model_config = ConfigDict(extra="forbid")
+
+
+class Task(BaseModel):
+    """Core task object - the unit of work."""
+
+    task_id: str = Field(..., description="Unique task identifier")
+    channel_id: str = Field(..., description="Channel where task originated/reports to")
+    agent_occurrence_id: str = Field(default="default", description="Runtime occurrence ID that owns this task")
+    description: str = Field(..., description="What needs to be done")
+    status: TaskStatus = Field(default=TaskStatus.PENDING)
+    priority: int = Field(default=0, ge=0, le=10, description="Priority 0-10")
+    created_at: str = Field(..., description="ISO8601 timestamp")
+    updated_at: str = Field(..., description="ISO8601 timestamp")
+    parent_task_id: Optional[str] = Field(None, description="Parent task for nested work")
+    context: Optional[TaskContext] = Field(None, description="Task context")
+    outcome: Optional[TaskOutcome] = Field(None, description="Outcome when complete")
+    # Task signing fields
+    signed_by: Optional[str] = Field(None, description="WA ID that signed this task")
+    signature: Optional[str] = Field(None, description="Cryptographic signature of task")
+    signed_at: Optional[str] = Field(None, description="ISO8601 timestamp when signed")
+    # Updated info tracking
+    updated_info_available: bool = Field(
+        default=False, description="Flag indicating new observation arrived for this task"
+    )
+    updated_info_content: Optional[str] = Field(
+        None, description="New observation content that arrived after task creation"
+    )
+    # Native multimodal support - images attached to task flow through to LLM
+    images: List[ImageContent] = Field(
+        default_factory=list, description="Images attached to this task for multimodal processing"
+    )
+
+    model_config = ConfigDict(extra="forbid")
+
+
+class Thought(BaseModel):
+    """Core thought object - a single reasoning step."""
+
+    thought_id: str = Field(..., description="Unique thought identifier")
+    source_task_id: str = Field(..., description="Task that generated this thought")
+    agent_occurrence_id: str = Field(default="default", description="Runtime occurrence ID (inherited from task)")
+    channel_id: Optional[str] = Field(None, description="Channel where thought operates")
+    thought_type: ThoughtType = Field(default=ThoughtType.STANDARD)
+    status: ThoughtStatus = Field(default=ThoughtStatus.PENDING)
+    created_at: str = Field(..., description="ISO8601 timestamp")
+    updated_at: str = Field(..., description="ISO8601 timestamp")
+    round_number: int = Field(0, ge=0, description="Processing round")
+    content: str = Field(..., description="Thought content/reasoning")
+    context: Optional[ThoughtContext] = Field(None, description="Thought context")
+    thought_depth: int = Field(0, ge=0, le=7, description="Pondering depth")
+    ponder_notes: Optional[List[str]] = Field(None, description="Notes from pondering")
+    parent_thought_id: Optional[str] = Field(None, description="Parent if pondering")
+    final_action: Optional[FinalAction] = Field(None, description="Action chosen")
+    # Native multimodal support - images inherited from source task
+    images: List[ImageContent] = Field(
+        default_factory=list, description="Images from source task for multimodal processing"
+    )
+
+    model_config = ConfigDict(extra="forbid")
+
+
+__all__ = [
+    "ImageContent",
+    "Task",
+    "Thought",
+    "TaskContext",
+    "TaskOutcome",
+    "ThoughtContext",
+    "FinalAction",
+]