CONTEXT.md

Rama main · réplica de lectura del repositorio original.

# Context

## Domain terms

- **Conversation intake**: The platform-message entry flow that decides whether an incoming chat message should start an agent run. It includes magic-word recognition, explicit addressing policy, attachment preparation, conversation log writing, busy policy, queue selection, and dispatch to the runtime handler.
- **Magic word**: A highest-priority chat control phrase that bypasses normal trigger policy and queueing rules, such as `stop`. Conversation intake owns the single magic-word grammar for every platform; platform adapters state only policy data (addressed?, stop scope fallback). Magic words should stay rare and narrowly scoped because they override normal conversation intake behavior.
- **Bare command**: A command phrase accepted without a leading slash. Bare commands should be limited to `session`; other commands require slash form to avoid accidental activation. `stop` is not treated as a normal bare command because it is a magic word.
- **Slash command**: A minimal chat control for essential, frequently needed actions. Slash commands are not a complete configuration surface and should not mirror every Admin capability.
- **Admin**: The complete operator-facing configuration surface. Detailed or infrequent settings belong in Admin rather than slash commands.
- **Platform Adapter**: Slack, Discord, Telegram, or GitHub code that translates platform SDK events into mikan conversation events and provides platform-specific response operations.
- **Response source**: Platform-neutral assistant-authored content expressed as standard Markdown/GFM. A Platform Adapter owns conversion from the response source into the platform's native presentation format; platform-native markup is not part of the response source contract, and an adapter must never steer the model toward platform-native markup — conversion is wholly the adapter's responsibility.
- **Progressive renderer**: The Platform Adapter module that owns how an in-progress response becomes a visible platform message over time — provisional renders while text accumulates, then one canonical final render. Callers never learn which platform mechanism (native streaming or message edits) produced the display.
- **Session key**: The office's platform session reference used to serialize and resume work for a direct message, shared channel, or thread. A session key belongs to exactly one conversation: either the bare conversation identity or that identity plus an opaque scoped suffix. It is a platform value, not globally unique — runtime state is always addressed by the Conversation office's `OfficeAddress` plus the session key, so a session key can never select another office's runtime state, even across platforms that share raw conversation IDs.
- **Session suffix**: The opaque platform thread, reply-root, or message identity after the session-key separator. It may distinguish scoped sessions but is never a separate conversation identity; path-dangerous values are invalid.
- **Clean session**: A newly created session with no transient context from its predecessor. `/new` creates a Clean session immediately; it does not summarize, preserve, or reorganize the previous session. Durable Conversation memory remains available separately through `MEMORY.md`.
- **Memory anchor**: The compact, revisable orientation in a Conversation office's `MEMORY.md`, written by the agent during runs. It helps a future session recover identities, decisions, preferences, open threads, and where to look next; it is evidence-backed context, not final truth. When an anchor conflicts with newer Conversation evidence or a Live source, the newer authoritative evidence wins and the agent updates the anchor.
- **Live source**: An external system whose mutable state is authoritative only when queried, such as an issue tracker, calendar, deployment system, or financial API. Conversation memory may retain stable identifiers and instructions for querying a Live source, but cached observations such as current status, counts, balances, assignments, and latest results are not authoritative; an answer about them requires a fresh source read in the current run.
- **Scheduled event**: A host-only JSON record under the owning office's state dir (`conversations/<office-key>/events/`), managed only through the `event` tool or Admin, that triggers an autonomous agent run — immediate, one-shot (`at`), or periodic (`schedule` + `timezone`). The scheduling tool and scheduler share one file-format contract, including the required fields for each event type. Scheduled events are execution requests, not the model/tool events produced during an agent run.

## Execution surfaces

- **Default office runtime**: The persistent, single-node Sandbox runtime assigned to one Conversation office. It provides strong environment isolation and a durable Workspace projection that survives turns and runtime restarts. The managed `oci:*` runtime belongs here. _Avoid_: treating a remote ephemeral worker as a default office.
- **OCI sandbox**: The `--sandbox=oci:<image>` backend for Default office runtimes: mikan creates and manages one container per Conversation office from an OCI image, on whichever engine (nerdctl, Podman, Docker) is available. _Formerly_: `image:<image>`, still accepted with a deprecation warning.
- **Factory floor**: An elastic execution surface for repetitive, outsourced, or highly parallel work. Each factory job receives a temporary environment and temporary data, returns an explicit result, and is then discarded. Kubernetes Agent Sandbox, Cloud Run sandbox, Cloudflare Sandbox, and E2B are intended future adapters. A Factory floor is not a Conversation office and never becomes the default persistent runtime.
- **Factory worker**: An agent run assigned to one ephemeral Factory floor job. It receives only explicitly packaged inputs and capabilities, cannot assume durable local state, and must return all durable results before teardown.
- **Task executor**: The lower-level ephemeral command surface behind a Factory floor: one task in, explicit output back, no persistent Workspace projection. A future Factory worker may orchestrate several task executions, but persistence still belongs to the Default office runtime.
- **Sandbox runtime**: A persistent execution environment capable of holding a Workspace projection across turns. In the office model, this is the agent's computer. _Avoid_: using the term for ephemeral factory capacity merely because that capacity is isolated.

### Deployment constraint

Default office runtimes are single-node by design. Moving a live office between nodes requires durable workspace transport, communication routing, and migration semantics that mikan does not currently promise. Elastic multi-node capacity belongs to the Factory floor, where jobs and data are disposable by contract.

## Workspace, isolation, and communication

- **Conversation office**: One conversation's personal working area and persistent data boundary. It contains the conversation's workspace and is paired with an independent Sandbox runtime. _Avoid_: treating a conversation office as merely a directory.
- **Office visibility**: The one data-policy dimension of a Conversation office (ADR 0008): `public` or `private`, derived from the platform conversation type. Slack public channels are public; private channels, DMs, group DMs, externally shared, and unknown conversations, and every Telegram, Discord, or GitHub conversation, are private. An operator may narrow a public conversation to private, never widen. Visibility does not change execution-environment or network isolation. _Avoid_: door policy, isolated/trusted/full, which named the retired five-way menu.
- **Public office**: An office every other office may read (read-only, under `/workspace/public/<key>`) and that may write the workspace-global MEMORY.md and skills.
- **Private office**: An office visible only to itself. It reads every public office and the workspace-global knowledge, but writes only its own directory.
- **Conversation communication**: Host-mediated communication between Conversation offices. Calls provide request/response delegation; messages provide durable asynchronous delivery. Communication passes messages or work results, not filesystem access or execution-environment ownership.
- **Shared bulletin**: Organization-level information intentionally published for multiple conversations. Read and write capabilities are independent of Conversation communication and Office visibility.
- **Workspace**: One mikan deployment's organizational agent world: its Conversation offices, shared information, and communication facilities. A Workspace is not necessarily one trust domain; office visibility determines which conversation data crosses office boundaries.
- **Workspace projection**: The explicit data view presented to a Sandbox runtime. Every projection has the same shape: the office's own directory read-write, every other public office read-only under `/workspace/public/`, and the workspace-global knowledge read-write (public office) or read-only (private office). No projection mounts the workspace root.
- **Office registry**: The host-only directory of Conversation offices (`office-registry.json` in the State dir). Office directories are named by office key — platform-scoped, collision-resistant, and not reversible to raw platform ids — so the registry records each office's `(platform, conversationId)` at creation and journals legacy-directory migrations. Raw-id-scoped surfaces (Admin) resolve offices through it.
- **Host workspace root**: The directory on the mikan host machine that stores workspace data.
- **Runtime workspace root**: The path at which an authorized Workspace projection appears inside a conversation's Sandbox runtime. The model only ever sees runtime paths.
- **State dir**: mikan's host-only private storage for settings, credentials, and office records. It is never part of a Workspace projection.
- **Vault**: Host-only per-office store of development keys that R&D services need injected into the Sandbox runtime (env, and file mounts where required). It is not a general credential store; other external credentials go through OpenConnector ([ADR 0013](docs/adr/0013-vault-scoped-to-development-keys.md)).
- **Conversation integration identity**: A host-side service credential that identifies one Conversation office while using a shared external account. For OpenConnector, the runtime token name is `mikan:slack:<workspace-id>:<channel-id>` on Slack and `mikan:github:<conversation-id>` on GitHub, one per issue or pull request; provider OAuth remains shared in OpenConnector. The identity distinguishes offices for audit and revocation; it does not by itself restrict which connections an office may use.

## Security boundaries

- **Execution isolation**: Every Conversation office uses an independent Sandbox runtime—the agent's computer. Office visibility never weakens this boundary.
- **Data isolation**: A private office's files are reachable only from its own runtime. Public offices are readable by every office; nothing is writable across offices. Unknown conversation kinds fail closed to private without changing environment isolation.
- **Open network**: Sandbox runtimes have unrestricted network connectivity by default. Authority comes from explicitly injected credentials and capabilities, not network reachability.
- **Host-side integration provisioning**: OpenConnector's admin token may mint conversation runtime tokens only inside the mikan host process and may be sent only to the origin of the deployment default `OPENCONNECTOR_ENDPOINT`. The admin token does not enter settings, the Vault, or managed Sandbox projections; the minted runtime token is saved as an ordinary conversation `mcpServers` entry (host-only settings.json), after which OpenConnector is handled like any other MCP server. Host sandbox mode is non-isolated and cannot provide this protection.