---
status-class: canonical-spec
design-state: current
---
# Owner-private agent runtime and API design

This spec defines the current runtime/API contract for owner-private agents in channel and reply-thread conversations. The durable chat timeline is the parent channel/thread/DM timeline; owner-private execution context is hidden runtime state, not a user-addressable conversation target.

## 1. Product model

- Channel, reply-thread, and DM messages are stored in the parent `scope_messages` timeline.
- A private agent is not added to the parent `scope_memberships` set.
- A private agent may still author a parent message. That message is a normal parent timeline row and is public to users who can read the parent conversation.
- `scope_executions` represent owner-scoped private-agent context, visibility, wake, cursor, lifecycle, and source provenance. They are not Spaces, not transcripts, not composer targets, and not agent-facing target strings.
- Task discussion, checkpoint, and artifact surfaces remain task-native and are not folded into `scope_messages`.

## 2. Delivery target contract

A private-agent delivery has two layers:

1. **Visible target**: the parent conversation target the agent can reuse, such as `#channel`, `#channel:threadShortId`, `dm:@user`, or a task-native target.
2. **Hidden context**: authenticated runtime/session metadata containing at least the owner member, source scope, parent delivery target, current delivery source, and the relevant `scope_executions` row.

The visible prompt header and MCP/API `target` parameters use only the parent target. Runtime/session hidden context is the only authorization source for owner-private filtered access. Agent-supplied hidden IDs must not be accepted as authority.

If hidden context is unavailable and the private agent is not a parent participant, the backend may only use explicitly allowed owner-private entry resolution. It must not grant full parent access by default.

## 3. Parent-target send contract

Agent-facing send APIs keep one verb: send to a target. The target is always a parent conversation target.

- Public agents and humans follow ordinary parent membership authorization.
- Private agents authorize through the current hidden owner-private context or a concrete private entry in the parent host channel.
- Private-agent sends write directly to the parent timeline.
- Attachments follow the same parent-row authorization as the message being sent.
- Reply-thread sends require the reply-thread root parent message to be visible in the current owner-private context.

A user request that starts a reply thread for a private-agent mention creates the parent message, opens the reply-thread channel for that parent row, and binds the sparse private-agent delivery to the new reply-thread target. The private agent therefore wakes on the parent thread target, not the channel main target.

## 4. Read, search, reaction, file, and review authorization

Every agent-facing operation that touches parent rows must apply the same owner-private visibility boundary:

- history reads and message search return only filtered-visible parent rows plus explicit source items;
- reaction add/remove is allowed only for filtered-visible parent/source items;
- attachment reads are allowed only for filtered-visible parent/source items;
- reply-thread creation and short-id resolution require the root parent row to be filtered-visible;
- rewind/recovery and review-context operations may only act on messages or thread scopes visible to the current owner-private context.

The root parent visibility check for reply thread scopes is a shared store helper. Handlers must not reimplement separate ad-hoc rules.

## 5. Sparse delivery and unread state

Sparse delivery facts must carry both parent display information and owner-private context information:

- the parent delivery/display space, used to format the visible target;
- the `scope_executions` context, used for owner-private visibility, cursor, unread, wake, and authorization.

Unread/cursor state for owner-private delivery is scoped by execution context and agent member, or by an equivalent owner-private key. Different owner/private contexts that point at the same parent channel must not share unread state.

A sparse event that points at a parent message stores that parent message id as the event source. A sparse event that points at an explicit virtual source item stores the stable source fact id or source message id.

## 6. Explicit source items

The private context view is a merge of:

1. parent rows visible under the owner-private filter;
2. explicit source facts that were shared into the private context.

A source fact is a virtual context item. It is not a copied message row and not a second parent timeline entry. It stores stable source provenance, including source target, source message id, source author/timestamp, shared-by member, captured content preview, attachment metadata, capture time, dedupe key, and fallback behavior for deleted or no-longer-visible sources.

Ordering and pagination must be deterministic. Parent rows use parent sequence/global sequence. Source facts use one fixed source ordering key, such as capture global sequence or share creation time. A source message that is already represented by a visible parent row must not be shown again as a duplicate virtual item.

## 7. Provider watches

Provider watch targets are parent conversations or task-native surfaces. Provider tool schemas and persisted watch bindings must not expose hidden private context IDs.

If a provider feature intentionally shares provider output into an owner-private context, it must create/update an explicit source or visibility fact. It must not create a second transcript row or a hidden copy.

## 8. Lifecycle

Removing a private agent, an owner leaving a channel, and archived/read-only surfaces affect owner-private delivery and context state only. They must not delete parent messages.

- Removing and later re-adding a private agent keeps parent history intact. The re-added private agent can see parent rows that match the current owner-private filter and explicit source facts according to the lifecycle policy.
- If the owner loses parent access, owner-private wake stops. Historical context may remain read-only only when the lifecycle policy explicitly allows it.
- Archived/read-only views are bounded by parent sequence/global sequence and source-fact capture time, not by a separate transcript sequence.

## 9. Removed product surfaces

There is no parent-row hiding preference for private-agent output. Since private-agent output is a normal parent row, all users who can read the parent conversation see it under the ordinary parent history rules.

There is no browser composer, route, or API surface for a separate private-agent transcript. Current user-facing surfaces are parent conversations, task-native surfaces, and private-agent management/notification controls.