# Shared

## Domain Types

### Account Resource Metadata

- `class AccountResourceMetadata`

  AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace.

  - `id: String`

    Unique identifier for the resource (prefixed ULID, e.g., "apikey_01HXK...")

  - `account_id: String`

    Account this resource belongs to for multi-tenant isolation (prefixed ULID)

  - `name: String`

    Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")
    Required for resources that users interact with directly

  - `profile_id: String`

  - `external_id: String`

    External ID for the resource (e.g., a workflow ID from an external system)

  - `labels: Hash[Symbol, String]`

    Arbitrary key-value pairs for categorization and filtering
    Examples: {"environment": "production", "team": "platform", "version": "v2"}

### Bare Metadata

- `class BareMetadata`

  BareMetadata contains the minimal metadata for a resource: the ID and an
  optional human-readable name. These are used for reference fields where the
  full metadata (account scoping, timestamps, labels, external IDs) is not
  needed — e.g., the tool references inside an agent variation spec or the
  tools assigned to an objective. Both fields are server-populated; clients
  provide IDs through sibling fields rather than by constructing a
  BareMetadata themselves.

  - `id: String`

  - `name: String`

    Human-readable name of the referenced resource, populated by the server
    on reads for convenience. Absent on references to resources that do not
    have a name (e.g., objective tasks).

### Create Operation Metadata

- `class CreateOperationMetadata`

  CreateOperationMetadata contains the user-provided fields for creating
  an operation. Read-only fields (id, account_id, workspace_id, created_at, profile_id)
  are excluded since they are set by the server.

  - `external_id: String`

    External ID for the operation (e.g., a workflow ID from an external system)

  - `labels: Hash[Symbol, String]`

    Arbitrary key-value pairs for categorization and filtering
    Examples: {"priority": "high", "source": "api", "workflow": "onboarding"}

### Create Resource Metadata

- `class CreateResourceMetadata`

  CreateResourceMetadata contains the user-provided fields for creating
  a workspace-scoped resource. Read-only fields (id, account_id, workspace_id, profile_id,
  created_at) are excluded since they are set by the server.

  - `name: String`

    Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")

  - `bundle_key: String`

    Optional bundle ownership key. See ResourceMetadata.bundle_key.

  - `external_id: String`

    External ID for the resource (e.g., a workflow ID from an external system)

  - `labels: Hash[Symbol, String]`

    Arbitrary key-value pairs for categorization and filtering
    Examples: {"environment": "production", "team": "platform", "version": "v2"}

### Operation Metadata

- `class OperationMetadata`

  Metadata for ephemeral operations and activities (e.g., objectives, executions, runs)

  - `id: String`

    Unique identifier for the operation (prefixed ULID, e.g., "obj_01HXK...")

  - `account_id: String`

    Account this operation belongs to for multi-tenant isolation (prefixed ULID)

  - `created_at: Time`

    Timestamp when this operation was created
    ULID includes timestamp information, but this explicit field enables easier querying

  - `profile_id: String`

    ID of the actor (user or service account) that created this operation

  - `workspace_id: String`

    Workspace this operation belongs to for organizational grouping (prefixed ULID)

  - `external_id: String`

    External ID for the operation (e.g., a workflow ID from an external system)

  - `labels: Hash[Symbol, String]`

    Arbitrary key-value pairs for categorization and filtering
    Examples: {"priority": "high", "source": "api", "workflow": "onboarding"}

### Resource Metadata

- `class ResourceMetadata`

  Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

  - `id: String`

    Unique identifier for the resource (prefixed ULID, e.g., "agent_01HXK...")

  - `account_id: String`

    Account this resource belongs to for multi-tenant isolation (prefixed ULID)

  - `created_at: Time`

    Timestamp when this resource was created

  - `name: String`

    Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")
    Required for resources that users interact with directly

  - `profile_id: String`

    ID of the actor (user or service account) that created this resource

  - `workspace_id: String`

    Workspace this resource belongs to for organizational grouping (prefixed ULID)

  - `bundle_key: String`

    Optional bundle ownership key. When set, indicates the resource is
    managed by a configuration bundle identified by this key. Used by
    BulkWorkspaceResources.Apply to track which resources belong to which
    bundle for reconciliation / soft-delete on re-apply.

  - `external_id: String`

    External ID for the resource (e.g., a workflow ID from an external system)

  - `labels: Hash[Symbol, String]`

    Arbitrary key-value pairs for categorization and filtering
    Examples: {"environment": "production", "team": "platform", "version": "v2"}

### Update Resource Metadata

- `class UpdateResourceMetadata`

  UpdateResourceMetadata contains the user-provided fields for updating
  a workspace-scoped resource. Read-only fields (id, account_id, workspace_id, profile_id,
  created_at) are excluded since they are set by the server.

  - `name: String`

    Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")

  - `bundle_key: String`

    Optional bundle ownership key. See ResourceMetadata.bundle_key.

  - `external_id: String`

    External ID for the resource (e.g., a workflow ID from an external system)

  - `labels: Hash[Symbol, String]`

    Arbitrary key-value pairs for categorization and filtering
    Examples: {"environment": "production", "team": "platform", "version": "v2"}