# Shared

## Domain Types

### Account Resource Metadata

- `AccountResourceMetadata = object { id, accountId, name, 3 more }`

  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...")

  - `accountId: 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

  - `profileId: string`

  - `externalId: optional string`

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

  - `labels: optional map[string]`

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

### Bare Metadata

- `BareMetadata = object { id, name }`

  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: optional string`

  - `name: optional 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

- `CreateOperationMetadata = object { externalId, labels }`

  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.

  - `externalId: optional string`

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

  - `labels: optional map[string]`

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

### Create Resource Metadata

- `CreateResourceMetadata = object { name, externalId, labels }`

  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")

  - `externalId: optional string`

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

  - `labels: optional map[string]`

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

### Operation Metadata

- `OperationMetadata = object { id, accountId, createdAt, 4 more }`

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

  - `id: string`

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

  - `accountId: string`

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

  - `createdAt: string`

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

  - `profileId: string`

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

  - `workspaceId: string`

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

  - `externalId: optional string`

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

  - `labels: optional map[string]`

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

### Resource Metadata

- `ResourceMetadata = object { id, accountId, createdAt, 5 more }`

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

  - `id: string`

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

  - `accountId: string`

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

  - `createdAt: string`

    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

  - `profileId: string`

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

  - `workspaceId: string`

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

  - `externalId: optional string`

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

  - `labels: optional map[string]`

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

### Update Resource Metadata

- `UpdateResourceMetadata = object { name, externalId, labels }`

  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")

  - `externalId: optional string`

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

  - `labels: optional map[string]`

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