Primitives

Company OS provides five foundational primitives that compose all agent actions. These primitives are implemented in a specific build order, with each layer depending on the previous one. Together, they form the core abstractions through which the OS mediates every agent action, enforcing security, metering, and policy.

Build Order and Relationships

The primitives are built in this sequence: Principal → Capability → Task → Receipt → Policy. Each primitive represents a distinct concern, and later primitives build upon the guarantees and data provided by earlier ones.

flowchart TD
    subgraph Build Order
        direction TB
        A[Principal] --> B[Capability]
        B --> C[Task]
        C --> D[Receipt]
        D --> E[Policy]
    end
    classDef primitive fill:#f9f9f9,stroke:#333,stroke-width:1px;
    class A,B,C,D,E primitive;

Principal

Owner: Tenant, user, agent, or factory (with designated human accountable principal)
Exists in Job Intelligence: Only user via Better Auth

The Principal primitive represents an identity capable of acting within the system. It encompasses tenants, users, agents, and factories. Agents possess their own credentials and a designated human accountable principal. Crucially, the Principal includes an identity crosswalk that resolves channel-specific identifiers (e.g., WhatsApp number, Teams user ID, Better Auth session) to a single principal, preventing implicit principal creation. Only tenant administrators may link channel identities to a principal.

Evidence: The Principal primitive is defined in ADR-0001 as the first primitive, owned by tenant, user, agent, or factory, with an identity crosswalk over channels. The overview confirms it prevents implicit principal creation and requires tenant-admin linking. {repo://docs/adr/ADR-0001-company-os-multi-tenant-metered.md#L71} {repo://openwiki/architecture/overview.md#L44-L45}

Capability

Owner: Applications register schema, permission, effect class, and reversibility; the OS is the sole invoker
Exists in Job Intelligence: Yes (JI-only, 20 capabilities)

A Capability is an invocable function defined by an application. It specifies an input/output schema, permission requirements, effect class (e.g., read, write, delete), and reversibility. The Company OS is the sole invoker of capabilities; applications do not call them directly. This centralization allows the OS to enforce security, metering, and policy uniformly.

Evidence: The Capability primitive is defined in ADR-0001 as the second primitive, owned by applications for registration and by the OS as the sole invoker. The overview confirms applications register capabilities and the OS is the sole invoker. {repo://docs/adr/ADR-0001-company-os-multi-tenant-metered.md#L72} {repo://openwiki/architecture/overview.md#L47-L48}

Task

Owner: Encapsulates intent + actor + tenant + goal + approval class
Exists in Job Intelligence: Stub (complete_task)

A Task encapsulates an intention to perform work. It comprises the actor (principal), goal, tenant context, and approval class. Tasks are routed deterministically for fixed agents (e.g., Ops agents) or via model-driven routing for others. The Task primitive is a flow descriptor, not a storage unit; it correlates actions but does not persist state beyond the action’s execution.

Evidence: The Task primitive is defined in ADR-0001 as the third primitive, comprising intent, actor, tenant, goal, and approval class. The overview describes it as encapsulating intention to perform work and being routed deterministically or model-driven. {repo://docs/adr/ADR-0001-company-os-multi-tenant-metered.md#L73} {repo://openwiki/architecture/overview.md#L50-L51}

Receipt

Owner: Every action/tool call: correlation-ID, costs, outcome, parent
Exists in Job Intelligence: Audit-event (without tenant/costs)

The Receipt primitive records every atomic action or tool call executed by the OS. It contains: correlation ID (linking to the initiating task), tenant ID, principal ID, capability invoked, effect class, target, costs (model and infrastructure in cents), token usage, Langfuse trace ID, outcome (pending, success, failed, denied, uncertain), and timestamps. Receipts form the immutable basis for billing and auditing; every action generates exactly one Receipt. The capability-invoke is the billable event, with tool calls and model costs recorded as child receipts via parent_receipt_id.

Evidence: The Receipt primitive is defined in ADR-0001 as the fourth primitive, capturing correlation-ID, costs, outcome, and parent. The overview details its structure and role as the immutable basis for billing and auditing. {repo://docs/adr/ADR-0001-company-os-multi-tenant-metered.md#L74} {repo://openwiki/architecture/overview.md#L53-L54} {repo://docs/adr/ADR-0001-company-os-multi-tenant-metered.md#L104-L111}

Policy

Owner: Approval-as-data per role and effect class, with goal, limits, validity, stop conditions
Exists in Job Intelligence: Only snapshot-approval

The Policy primitive encodes approval logic as data. It specifies applicable roles, effect classes, goals, limits, validity periods, and stop conditions. Policies are evaluated by the OS before action execution, replacing hardcoded approval checks. This allows dynamic, context-aware authorization without code changes.

Evidence: The Policy primitive is defined in ADR-0001 as the fifth primitive, encoding approval-as-data. The overview describes it as specifying roles, effect classes, goals, limits, validity, and stop conditions, evaluated before action execution. {repo://docs/adr/ADR-0001-company-os-multi-tenant-metered.md#L75} {repo://openwiki/architecture/overview.md#L56-L57}

Consumer Systems

Channel ingress, admin UI, skills library, and BI systems consume these five primitives but are not primitives themselves. They rely on the primitives to enforce tenant isolation, principal identity, metering, and factory restrictions.

Evidence: The overview explicitly states that channel ingress, admin UI, skills library, and BI systems consume the primitives but are not primitives themselves. {repo://openwiki/architecture/overview.md#L59}