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 normalized conversation input and one response port;
2. one runtime that serializes a session and owns runner lifecycle;
3. one harness interface for a model turn;
4. one session store and one platform log store, intentionally separate;
5. one executor interface for all tool I/O;
6. one credential-resolution seam;
7. 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
P0	The npm boundary is wider than the supported product boundary	src/index.ts uses export * from "./harness/index.js"; package metadata has no exports map	Declare explicit root exports and subpaths; stop publishing internal helpers accidentally
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 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: {
    id: string;
    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 {
  workingDir: string;
  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

1. Add a package exports map for ., ./extension, and ./runtime.
2. Replace the root export * with an explicit list.
3. Add API-extractor-style snapshot tests using emitted declarations or a checked symbol list.
4. Mark currently exported-but-unsupported symbols deprecated for one release before removal.

This is first because every internal refactor is harder after consumers depend on accidental exports.

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 first pull request

Keep the first implementation PR behavior-neutral:

1. add the package exports map with compatibility subpaths;
2. replace duplicate root type re-exports with explicit exports;
3. add a public API snapshot test;
4. introduce ConversationInput plus conversion helpers, but migrate only one adapter;
5. 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.