Core simplification

This audit uses the boundaries in Core interface reference. The goal is not to minimize file count; it is to make the core explainable as a small set of stable contracts and move optional policy behind them.

Target core

The smallest coherent mikan core is:

1. one conversation identity and one place that turns it into paths;
2. one normalized conversation input and one response port;
3. one runtime that serializes a session and owns runner lifecycle;
4. one harness interface for a model turn;
5. one session store and one platform log store, intentionally separate;
6. one executor interface for all tool I/O;
7. one credential-resolution seam;
8. registries for optional platform, command, tool, extension, and sandbox capabilities.

Web portals, particular chat SDKs, Docker provisioning, Gondolin runtime management, Firecracker, Cloudflare, and GitHub-specific tools are products or plugins around this core.

Findings

Priority	Finding	Evidence	Simplification
Done	The npm boundary is explicit and regression-tested	src/index.ts lists root exports; package.json declares root, harness, and sandbox entry points; src/test/public-api.test.ts snapshots runtime exports	Treat additions as compatibility decisions and update the contract test deliberately
Done	Conversation identity and path derivation have one owner	src/office/ owns OfficeAddress/OfficeKey, the Workspace/Office values, the registry, and the legacy migration; consumers take values, not strings	Keep path math inside the module; a new consumer receives an Office rather than a root plus an id
P0	Platform input has two overlapping canonical shapes	ConversationEvent and ConversationMessage repeat id/session/kind/user/text/attachments/thread fields and are passed together	Introduce one ConversationInput envelope; derive compatibility views during migration
P0	MessagingBot has too many reasons to change	lifecycle, output, upload/reaction, private diagnostics, event queue, and metadata are one interface	Split normalized platform port from optional capabilities; keep one adapter object that composes them
P1	Sandbox extensibility is only nominal	SandboxAdapter is exported, but a closed array in sandbox/index.ts owns parsing/creation	Add a registry or make adapters internal; move experimental backends out of the default core assembly
P1	Runtime construction leaks command implementation details	ConversationRuntimeOptions is an Omit<CommandServices, ...> and reconstructs command services internally	Define explicit runtime dependencies, then build CommandServices in a command adapter
P1	Commands still have two inventories	The manifest owns platform registration while the registry owns handlers; adding a command requires both	A CommandDefinition should contain manifest metadata and a handler factory/reference
P1	The harness is both a public SDK and an internal engine	Root exports session parsing, credentials, settings, loader, event schema, hooks, and runner details together	Publish ./extension, ./runtime, and optionally ./harness subpaths with separate stability policies
P2	Optional runtime products are compiled into the central CLI	Platform SDKs, portals, six sandbox modes, and Gondolin runtime code are assembled in main.ts	Make main.ts a composition root over registries; lazy/optional product modules become replaceable
P2	Several capability interfaces use optional methods	MessagingBot and ConversationResponder grow by adding ? methods	Use named capability objects (reactions, uploads, streaming) so absence and requirements are explicit
P2	HTTP route contracts are manually dispatched and mostly untyped	web/server.ts and portal modules branch on method/path; payload types are local	Keep the UI API internal, but centralize route descriptors and request/response schemas where payloads cross modules

What should not be simplified away

Some apparent duplication protects important semantics:

• Keep log.jsonl separate from agent session JSONL. They record different truths and support recovery.
• Keep office keys distinct from raw platform ids. Naming a directory or a vault by a raw id lets two platforms that share an id reach each other’s data; the registry exists precisely because the key is not reversible.
• Keep session keys raw. They are platform values, and pairing them with an office is what makes a non-globally-unique key safe — rewriting them into office-scoped strings would move the check from the runtime into every caller.
• Keep host paths separate from runtime paths. Collapsing them breaks container/remote execution and can expose host-only data.
• Keep model-provider credentials separate from sandbox vault credentials.
• Keep per-session queues. Global serialization would waste concurrency; no serialization would corrupt conversation order.
• Keep platform trust policy explicit. Inferring credential safety from platform names is unsafe.
• Keep executor-owned file transport. Replacing it with shell snippets reintroduces quoting, size, and partial-write failures.
• Keep extension code host-only and sandbox workspace data separate.

Proposed interfaces

One normalized input

interface ConversationInput {
  platform: MessagingInfo;
  conversation: {
    address: OfficeAddress;
    kind: ConversationKind;
    vaultId?: string;
  };
  message: {
    id: string;
    parentId?: string;
    sessionKey?: string;
    actor: { id: string; name?: string };
    text: string;
    attachments: readonly Attachment[];
  };
  respond: ConversationResponder;
}

The runtime derives ConversationEvent and ConversationMessage only for old call sites. Once adapters and tests use the envelope, delete both compatibility shapes.

Composed platform capabilities

interface PlatformPort {
  readonly info: MessagingInfo;
  lifecycle: { start(): Promise<void>; stop(): Promise<void> };
  messages: PlatformMessages;
  capabilities?: {
    reactions?: PlatformReactions;
    uploads?: PlatformUploads;
    privateMessages?: PlatformPrivateMessages;
  };
}

This removes feature detection by arbitrary method name and lets commands/extensions request the exact capability they need.

Explicit runtime dependencies

interface ConversationRuntimeOptions {
  workspace: Workspace;
  sandbox: SandboxConfig;
  createRunner: RunnerFactory;
  commands?: readonly CommandDefinition[];
  vault?: VaultResolver;
  resources?: SandboxResourceController;
  portals?: PortalServices;
  platformCapabilities?: PlatformCapabilities;
  platformToolPacks?: readonly PlatformToolPackFactory[];
}

The runtime should not inherit its constructor shape from another subsystem’s service bag.

Honest sandbox registry

interface SandboxRegistry {
  register<T extends SandboxConfig>(adapter: SandboxAdapter<T>): void;
  parse(value: string): SandboxConfig;
  validate(config: SandboxConfig): Promise<void>;
  createExecutor(config: SandboxConfig, context: ExecutorContext): Promise<Executor>;
}

The default CLI registers stable backends. Gondolin, Firecracker, and Cloudflare can be registered by optional product modules without changing tool or runtime code.

Migration sequence

Phase 1 — enforce the package boundary (complete)

1. package.json declares root plus compatibility ./harness and ./sandbox entry points.
2. The root entry point uses an explicit export list rather than a wildcard harness export.
3. src/test/public-api.test.ts snapshots runtime exports so accidental additions fail CI.

The remaining phases can now refactor internals without silently expanding the package interface.

Phase 2 — unify platform input

1. Add ConversationInput and an adapter from it to the current runtime call.
2. Convert one platform adapter and its tests at a time.
3. Change handleEvent(event, bot, context) to handle(input).
4. Delete duplicated fields and compatibility adapters after all platforms migrate.

This should remove consistency bugs around ts versus message.id, thread_ts versus threadTs, and event user versus message userId.

Phase 3 — compose capabilities

1. Extract message, reaction, upload, and private-message ports from MessagingBot.
2. Adapt existing bots without changing their SDK code.
3. Pass narrow capabilities to commands, extensions, events, and admin instead of the whole bot.
4. Retire ChatAdapter if no independent caller remains.

Phase 4 — simplify runtime construction and commands

1. Replace the Omit<CommandServices, ...> inheritance with explicit runtime options.
2. Make portal services one optional object rather than three token-store fields plus a URL.
3. Join command metadata and handler registration into CommandDefinition.
4. Generate platform registration, parsing inventory, and handler order from that definition list.

Phase 5 — separate optional execution products

1. Introduce SandboxRegistry while preserving the existing default functions as wrappers.
2. Register host/container/image as the default distribution.
3. Register Gondolin, Firecracker, and Cloudflare from optional composition modules.

Phase 6 — reduce the composition root

main.ts should parse CLI configuration, instantiate registries/services, start selected products, and coordinate shutdown. Platform SDK initialization and backend-specific policy should remain in their modules. A useful completion criterion is that the composition root reads like configuration, not business logic.

Acceptance criteria

The simplification is complete when:

• a new platform implements one normalized input adapter plus declared output capabilities;
• a new sandbox registers one adapter without editing a core switch or array;
• runtime construction does not mention individual portal token-store types;
• adding a command changes one definition and one handler implementation, not several platform inventories;
• the root npm declaration surface contains only documented symbols;
• persisted session/event/config formats and trust/path invariants remain compatible;
• existing unit tests, build, lint, and knip pass after each phase.

Recommended next pull request

The package-boundary work is complete. Keep the next implementation PR behavior-neutral:

1. introduce ConversationInput plus conversion helpers, but migrate only one adapter;
2. record deprecations without deleting functionality.

Do not combine this with removing a sandbox backend or changing persisted formats. Those changes have different rollback and operational risks.