@ikenga/contract 0.5.1 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ikenga/contract",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "description": "Shared contract for the Ikenga pkg system: manifest schema, RPC types, Engine interface, capability scopes.",
   "license": "Apache-2.0",
   "repository": {
@@ -24,8 +24,8 @@
       "import": "./dist/rpc.js"
     },
     "./engine": {
-      "types": "./dist/engine.d.ts",
-      "import": "./dist/engine.js"
+      "types": "./dist/engine/index.d.ts",
+      "import": "./dist/engine/index.js"
     },
     "./scopes": {
       "types": "./dist/scopes.d.ts",

package/src/{engine.ts → engine/acp.ts}

@@ -1,205 +1,16 @@
-// Engine adapter contract. Implementations:
-//   - engine-claude-code  (default, ships preinstalled)
-//   - engine-codex        (future)
-//   - engine-aider        (future)
-//   - engine-noop         (testing / shell-without-AI mode)
-
-import { z } from 'zod';
-
-export interface SessionOpts {
-  cwd?: string;
-  systemPrompt?: string;
-  toolAllowList?: string[];
-  /** Caller pkg id, used by the engine for per-pkg billing/audit. */
-  callerPkg?: string;
-}
-
-export interface Session {
-  readonly id: string;
-  /** Best-effort cancellation. Resolves once the engine has stopped streaming. */
-  cancel(): Promise<void>;
-}
-
-export type EngineEvent =
-  | { type: 'message_delta'; text: string }
-  | { type: 'tool_use'; tool: string; input: unknown; toolUseId: string }
-  | { type: 'tool_result'; toolUseId: string; output: unknown; isError?: boolean }
-  | { type: 'thinking_delta'; text: string }
-  | { type: 'usage'; inputTokens: number; outputTokens: number; cacheCreationTokens?: number; cacheReadTokens?: number }
-  | { type: 'done'; reason: 'stop' | 'cancel' | 'error'; error?: string };
-
-export interface McpServerSpec {
-  id: string;
-  command: string;
-  args?: string[];
-  env?: Record<string, string>;
-}
-
-// ---------- Capabilities (single source of truth) ----------
-
-/**
- * Capability flags every engine adapter advertises. This is the canonical
- * shape consumed by both the shell-side ChatAdapter layer and any pkg that
- * needs to reason about adapter features (wizard, settings UI, telemetry).
- *
- * Fields are intentionally a *superset* of what any single adapter
- * supports — an adapter sets the ones it implements to `true` and the
- * rest to `false`. Adding a new flag is a non-breaking schema change so
- * long as adapters default it to `false` until they implement it.
- */
-export const AgentCapabilitiesSchema = z.object({
-  /** Streams partial responses as they arrive (vs. all-at-once). */
-  streaming: z.boolean(),
-  /** Invokes external tools / function calls during a turn. */
-  toolUse: z.boolean(),
-  /** Emits an extended-thinking / reasoning channel separate from output. */
-  thinking: z.boolean(),
-  /** Produces structured artifacts (code blocks, files, images) the host renders. */
-  artifacts: z.boolean(),
-  /** Accepts file attachments as part of an input. */
-  fileAttachments: z.boolean(),
-  /** Accepts image input (vision). */
-  imageInput: z.boolean(),
-  /** Recognises a `/slash` command vocabulary. */
-  slashCommands: z.boolean(),
-  /** Lets the user switch models mid-thread. */
-  modelSwitching: z.boolean(),
-  /** Uses prompt-caching for repeated context (Anthropic-specific today). */
-  promptCaching: z.boolean(),
-  /** Runs agentic tools (recursive sub-agents, long-running loops). */
-  agenticTools: z.boolean(),
-  /** Speaks MCP — can register and route through MCP servers. */
-  mcp: z.boolean(),
-  /** Can resume a prior session by id. */
-  sessionResume: z.boolean(),
-});
-export type AgentCapabilities = z.infer<typeof AgentCapabilitiesSchema>;
-
-// ---------- Engine pkg manifest "engine" block ----------
-
-/**
- * Per-adapter onboarding requirements surfaced in the first-run wizard.
- * The wizard composes these instead of hardcoding per-agent forms —
- * every engine pkg owns its own setup story.
- */
-export const EngineOnboardingSchema = z.object({
-  /** Stronghold-vault keys this adapter needs at runtime (e.g. `ANTHROPIC_API_KEY`). */
-  requiredVaultKeys: z.array(z.string()).default([]),
-  /** Plain env-vars the adapter expects on the host shell. */
-  requiredEnvVars: z.array(z.string()).default([]),
-  /**
-   * CLI command the user can run to authenticate. The wizard surfaces this
-   * as a copy-to-clipboard hint — it never shells out on the user's behalf.
-   */
-  authCommand: z.string().optional(),
-  /** Docs URL for setting up this adapter. */
-  docsUrl: z.string().url().optional(),
-});
-export type EngineOnboarding = z.infer<typeof EngineOnboardingSchema>;
-
-/**
- * Manifest block declared by engine-* pkgs. Read by the shell's
- * `AdapterLoader` at pkg-discovery time; consumed by the wizard to compose
- * adapter-specific onboarding hints.
- */
-export const EngineProvidesSchema = z.object({
-  /**
-   * Stable id — matches the detection-side agent id (e.g. `claude-code`,
-   * `codex`, `aider`, `noop`). The wizard's `selected_agent_id` is matched
-   * against this field at adapter-resolve time.
-   */
-  agentId: z.string().min(1),
-  /** Display name; overrides any detection-side display if both present. */
-  display: z.string().optional(),
-  /** Snapshot of what this adapter implements. */
-  capabilities: AgentCapabilitiesSchema,
-  /** Onboarding requirements composed by the wizard. */
-  onboarding: EngineOnboardingSchema.default({
-    requiredVaultKeys: [],
-    requiredEnvVars: [],
-  }),
-});
-export type EngineProvides = z.infer<typeof EngineProvidesSchema>;
-
-// ---------- Engine adapter runtime contract ----------
-
-export interface Engine {
-  /** Stable identifier — matches the pkg id of the engine adapter. */
-  readonly id: string;
-
-  /** Human-readable adapter version. */
-  readonly version: string;
-
-  /**
-   * Static metadata copied from the loading manifest's `engine` block.
-   * Required: every adapter must surface its agentId / display / capabilities
-   * / onboarding so the shell and wizard can introspect without re-parsing
-   * the manifest.
-   */
-  readonly metadata: {
-    agentId: string;
-    display: string;
-    capabilities: AgentCapabilities;
-    onboarding: EngineOnboarding;
-  };
-
-  /** Open a new session. Sessions are cheap; create one per pkg invocation. */
-  startSession(opts: SessionOpts): Promise<Session>;
-
-  /** Send input and stream events. The iterable completes on `done`. */
-  stream(session: Session, input: string): AsyncIterable<EngineEvent>;
-
-  /** Register an MCP server with the engine. Idempotent on `id`. */
-  registerMcpServer(spec: McpServerSpec): Promise<void>;
-
-  /** Unregister an MCP server. */
-  unregisterMcpServer(id: string): Promise<void>;
-
-  /** Health check — used by the kernel before routing pkg requests. */
-  healthCheck(): Promise<{ ok: boolean; reason?: string }>;
-}
-
-// ---------- Adapter loader contract ----------
-
 /**
- * Loader the shell uses to bring engine-* pkgs online at boot, tear them
- * down on removal, and gracefully fall back when the user's
- * `selected_agent_id` has no installed adapter.
+ * ACP (Agent Client Protocol) shapes. Phase 10: a second, ACP-shaped
+ * contract sits alongside the legacy `Engine` interface in `./adapter.ts`.
+ * The two coexist while Phase 11 retires the legacy adapter. New engines
+ * (in-process Rust ACP, Node ACP sidecars, etc.) target `AcpEngine`;
+ * existing consumers keep the `Engine` shape until they migrate.
  *
- * Implementation lives shell-side (post-Phase-7); this interface lets
- * the contract pin the shape so engine pkgs and the shell agree on the
- * load lifecycle.
+ * Method names mirror ACP's verbatim so the wire layer and the adapter
+ * layer share vocabulary — `newSession`, `prompt`, `cancel`, `setMode`,
+ * `loadSession`, `forkSession`, `requestPermission`.
  */
-export interface AdapterLoader {
-  /**
-   * Load + register the engine for a given pkg manifest. The manifest must
-   * carry an `engine` block (see `EngineProvidesSchema`); the loader
-   * resolves the adapter implementation and threads the manifest's
-   * metadata into the returned `Engine.metadata`.
-   */
-  load(manifest: { id: string; engine: EngineProvides }): Promise<Engine>;
-
-  /** Unload — used on pkg removal. After this resolves the agentId is unregistered. */
-  unload(agentId: string): Promise<void>;
-
-  /**
-   * Fallback returned when the requested agentId has no registered loader.
-   * Implementations MUST return a working `engine-noop` (or equivalent
-   * inert) adapter so the chat surface never dead-ends.
-   */
-  fallback(): Engine;
-}
 
-// ─── ACP (Agent Client Protocol) shapes ───────────────────────────────────────
-//
-// Phase 10: a second, ACP-shaped contract sits alongside the legacy `Engine`
-// interface above. The two coexist while Phase 11 retires the legacy
-// adapter. New engines (in-process Rust ACP, Node ACP sidecars, etc.) target
-// `AcpEngine`; existing consumers keep the `Engine` shape until they migrate.
-//
-// The names mirror ACP's method names verbatim so the wire layer and the
-// adapter layer share vocabulary — `newSession`, `prompt`, `cancel`,
-// `setMode`, `loadSession`, `forkSession`, `requestPermission`.
+import type { McpServerSpec } from './adapter.js';
 
 /** ACP `ProtocolVersion`. Numeric. V1 = 1. */
 export type AcpProtocolVersion = number;
@@ -483,3 +294,43 @@ export interface AcpEngine {
   /** Subscribe to OS-attention notifications. Returns a sync unsubscribe. */
   onNotify(callback: (payload: AcpNotifyPayload) => void): () => void;
 }
+
+// ── Host bridge (ACP-shaped) ──────────────────────────────────────────────────
+
+/** Synchronous unsubscribe handle. */
+export type AcpUnlisten = () => void;
+
+/**
+ * Tauri-side surface the host shell exposes for the ACP engine. The shell
+ * binds these to its `acp_*` Tauri commands and `acp://*` event listeners.
+ *
+ * Each `on*` returns a Promise of an unsubscribe fn — the engine wraps that
+ * so callers get a sync unsubscribe.
+ */
+export interface AcpHost {
+  initialize(req: AcpInitializeRequest): Promise<AcpInitializeResponse>;
+  newSession(req: AcpNewSessionRequest): Promise<AcpNewSessionResponse>;
+  prompt(req: AcpPromptRequest): Promise<AcpPromptResponse>;
+  cancel(sessionId: string): Promise<void>;
+  setMode(sessionId: string, modeId: AcpSessionModeId): Promise<void>;
+  loadSession(sessionId: string): Promise<AcpLoadSessionResponse>;
+  forkSession(
+    sourceSessionId: string,
+    opts?: AcpForkOpts,
+  ): Promise<AcpForkResult>;
+  listenSession(
+    sessionId: string,
+    onUpdate: (notification: AcpSessionNotification) => void,
+  ): Promise<AcpUnlisten>;
+  listenPermissionRequests(
+    sessionId: string,
+    onRequest: (envelope: AcpPermissionRequestEnvelope) => void,
+  ): Promise<AcpUnlisten>;
+  respondPermission(
+    requestId: string,
+    response: AcpRequestPermissionResponse,
+  ): Promise<void>;
+  listenNotify(
+    callback: (payload: AcpNotifyPayload) => void,
+  ): Promise<AcpUnlisten>;
+}

package/src/engine/adapter.ts

@@ -0,0 +1,243 @@
+/**
+ * Legacy Engine adapter shape. New adapters target `./acp.ts`. Both are
+ * exported through `@ikenga/contract/engine` during the deprecation cycle.
+ *
+ * Engine adapter contract. Implementations:
+ *   - engine-claude-code  (default, ships preinstalled)
+ *   - engine-codex        (future)
+ *   - engine-aider        (future)
+ *   - engine-noop         (testing / shell-without-AI mode)
+ *
+ * @deprecated Phase 11 retires this surface. New adapters target the ACP
+ *   shape in `./acp.ts` (`AcpEngine`, `createAcpEngine`, `AcpHost`).
+ */
+
+import { z } from 'zod';
+
+/** @deprecated Use the ACP shape in `./acp.ts`. */
+export interface SessionOpts {
+  cwd?: string;
+  systemPrompt?: string;
+  toolAllowList?: string[];
+  /** Caller pkg id, used by the engine for per-pkg billing/audit. */
+  callerPkg?: string;
+  /** Model override for the session (adapter-specific). */
+  model?: string;
+  /** Resume a prior session by id (adapter-specific; requires sessionResume cap). */
+  resumeSessionId?: string;
+}
+
+/** @deprecated Use the ACP shape in `./acp.ts`. */
+export interface Session {
+  readonly id: string;
+  /** Best-effort cancellation. Resolves once the engine has stopped streaming. */
+  cancel(): Promise<void>;
+}
+
+/** @deprecated Use `AcpSessionUpdate` from `./acp.ts`. */
+export type EngineEvent =
+  | { type: 'message_delta'; text: string }
+  | { type: 'tool_use'; tool: string; input: unknown; toolUseId: string }
+  | { type: 'tool_result'; toolUseId: string; output: unknown; isError?: boolean }
+  | { type: 'thinking_delta'; text: string }
+  | { type: 'usage'; inputTokens: number; outputTokens: number; cacheCreationTokens?: number; cacheReadTokens?: number }
+  | { type: 'done'; reason: 'stop' | 'cancel' | 'error'; error?: string };
+
+/**
+ * MCP server spec. Shared between the legacy `Engine` surface and the ACP
+ * `newSession` request — not marked `@deprecated` because the ACP shape
+ * reuses it verbatim.
+ */
+export interface McpServerSpec {
+  id: string;
+  command: string;
+  args?: string[];
+  env?: Record<string, string>;
+}
+
+// ---------- Capabilities (single source of truth) ----------
+
+/**
+ * Capability flags every engine adapter advertises. This is the canonical
+ * shape consumed by both the shell-side ChatAdapter layer and any pkg that
+ * needs to reason about adapter features (wizard, settings UI, telemetry).
+ *
+ * Fields are intentionally a *superset* of what any single adapter
+ * supports — an adapter sets the ones it implements to `true` and the
+ * rest to `false`. Adding a new flag is a non-breaking schema change so
+ * long as adapters default it to `false` until they implement it.
+ */
+export const AgentCapabilitiesSchema = z.object({
+  /** Streams partial responses as they arrive (vs. all-at-once). */
+  streaming: z.boolean(),
+  /** Invokes external tools / function calls during a turn. */
+  toolUse: z.boolean(),
+  /** Emits an extended-thinking / reasoning channel separate from output. */
+  thinking: z.boolean(),
+  /** Produces structured artifacts (code blocks, files, images) the host renders. */
+  artifacts: z.boolean(),
+  /** Accepts file attachments as part of an input. */
+  fileAttachments: z.boolean(),
+  /** Accepts image input (vision). */
+  imageInput: z.boolean(),
+  /** Recognises a `/slash` command vocabulary. */
+  slashCommands: z.boolean(),
+  /** Lets the user switch models mid-thread. */
+  modelSwitching: z.boolean(),
+  /** Uses prompt-caching for repeated context (Anthropic-specific today). */
+  promptCaching: z.boolean(),
+  /** Runs agentic tools (recursive sub-agents, long-running loops). */
+  agenticTools: z.boolean(),
+  /** Speaks MCP — can register and route through MCP servers. */
+  mcp: z.boolean(),
+  /** Can resume a prior session by id. */
+  sessionResume: z.boolean(),
+});
+export type AgentCapabilities = z.infer<typeof AgentCapabilitiesSchema>;
+
+// ---------- Engine pkg manifest "engine" block ----------
+
+/**
+ * Per-adapter onboarding requirements surfaced in the first-run wizard.
+ * The wizard composes these instead of hardcoding per-agent forms —
+ * every engine pkg owns its own setup story.
+ */
+export const EngineOnboardingSchema = z.object({
+  /** Stronghold-vault keys this adapter needs at runtime (e.g. `ANTHROPIC_API_KEY`). */
+  requiredVaultKeys: z.array(z.string()).default([]),
+  /** Plain env-vars the adapter expects on the host shell. */
+  requiredEnvVars: z.array(z.string()).default([]),
+  /**
+   * CLI command the user can run to authenticate. The wizard surfaces this
+   * as a copy-to-clipboard hint — it never shells out on the user's behalf.
+   */
+  authCommand: z.string().optional(),
+  /** Docs URL for setting up this adapter. */
+  docsUrl: z.string().url().optional(),
+});
+export type EngineOnboarding = z.infer<typeof EngineOnboardingSchema>;
+
+/**
+ * Manifest block declared by engine-* pkgs. Read by the shell's
+ * `AdapterLoader` at pkg-discovery time; consumed by the wizard to compose
+ * adapter-specific onboarding hints.
+ */
+export const EngineProvidesSchema = z.object({
+  /**
+   * Stable id — matches the detection-side agent id (e.g. `claude-code`,
+   * `codex`, `aider`, `noop`). The wizard's `selected_agent_id` is matched
+   * against this field at adapter-resolve time.
+   */
+  agentId: z.string().min(1),
+  /** Display name; overrides any detection-side display if both present. */
+  display: z.string().optional(),
+  /** Snapshot of what this adapter implements. */
+  capabilities: AgentCapabilitiesSchema,
+  /** Onboarding requirements composed by the wizard. */
+  onboarding: EngineOnboardingSchema.default({
+    requiredVaultKeys: [],
+    requiredEnvVars: [],
+  }),
+});
+export type EngineProvides = z.infer<typeof EngineProvidesSchema>;
+
+/**
+ * Static metadata every adapter surfaces via `Engine.metadata`. Mirrors the
+ * manifest's `engine` block so the shell + wizard can introspect without
+ * re-parsing the manifest.
+ */
+export interface EngineMetadata {
+  agentId: string;
+  display: string;
+  capabilities: AgentCapabilities;
+  onboarding: EngineOnboarding;
+}
+
+// ---------- Host bridge (legacy) ----------
+
+/**
+ * Tauri-command surface the host shell exposes to legacy `Engine` adapters.
+ * The shell binds these names to its `claude_chat_*` commands; adapters
+ * never call `invoke()` directly so they remain testable.
+ *
+ * @deprecated Use the ACP shape (`AcpHost` in `./acp.ts`) for new adapters.
+ */
+export interface HostBridge {
+  spawn(opts: {
+    sessionId: string;
+    cwd?: string;
+    systemPrompt?: string;
+    model?: string;
+    resumeSessionId?: string;
+  }): Promise<void>;
+  send(sessionId: string, message: string): Promise<void>;
+  kill(sessionId: string): Promise<void>;
+  listen(sessionId: string): AsyncIterable<EngineEvent>;
+  registerMcp(spec: McpServerSpec): Promise<void>;
+  unregisterMcp(id: string): Promise<void>;
+}
+
+// ---------- Engine adapter runtime contract ----------
+
+/** @deprecated Use `AcpEngine` from `./acp.ts`. Legacy shape retired in Phase 11. */
+export interface Engine {
+  /** Stable identifier — matches the pkg id of the engine adapter. */
+  readonly id: string;
+
+  /** Human-readable adapter version. */
+  readonly version: string;
+
+  /**
+   * Static metadata copied from the loading manifest's `engine` block.
+   * Required: every adapter must surface its agentId / display / capabilities
+   * / onboarding so the shell and wizard can introspect without re-parsing
+   * the manifest.
+   */
+  readonly metadata: EngineMetadata;
+
+  /** Open a new session. Sessions are cheap; create one per pkg invocation. */
+  startSession(opts: SessionOpts): Promise<Session>;
+
+  /** Send input and stream events. The iterable completes on `done`. */
+  stream(session: Session, input: string): AsyncIterable<EngineEvent>;
+
+  /** Register an MCP server with the engine. Idempotent on `id`. */
+  registerMcpServer(spec: McpServerSpec): Promise<void>;
+
+  /** Unregister an MCP server. */
+  unregisterMcpServer(id: string): Promise<void>;
+
+  /** Health check — used by the kernel before routing pkg requests. */
+  healthCheck(): Promise<{ ok: boolean; reason?: string }>;
+}
+
+// ---------- Adapter loader contract ----------
+
+/**
+ * Loader the shell uses to bring engine-* pkgs online at boot, tear them
+ * down on removal, and gracefully fall back when the user's
+ * `selected_agent_id` has no installed adapter.
+ *
+ * Implementation lives shell-side (post-Phase-7); this interface lets
+ * the contract pin the shape so engine pkgs and the shell agree on the
+ * load lifecycle.
+ */
+export interface AdapterLoader {
+  /**
+   * Load + register the engine for a given pkg manifest. The manifest must
+   * carry an `engine` block (see `EngineProvidesSchema`); the loader
+   * resolves the adapter implementation and threads the manifest's
+   * metadata into the returned `Engine.metadata`.
+   */
+  load(manifest: { id: string; engine: EngineProvides }): Promise<Engine>;
+
+  /** Unload — used on pkg removal. After this resolves the agentId is unregistered. */
+  unload(agentId: string): Promise<void>;
+
+  /**
+   * Fallback returned when the requested agentId has no registered loader.
+   * Implementations MUST return a working `engine-noop` (or equivalent
+   * inert) adapter so the chat surface never dead-ends.
+   */
+  fallback(): Engine;
+}

package/src/{engine.test.ts → engine/engine.test.ts}

@@ -2,13 +2,14 @@ import { test } from 'node:test';
 import assert from 'node:assert/strict';
 import {
   AgentCapabilitiesSchema,
+  EngineNotImplementedError,
   EngineOnboardingSchema,
   EngineProvidesSchema,
   type AgentCapabilities,
   type Engine,
   type EngineProvides,
-} from './engine.js';
-import { ManifestSchema, PkgManifestSchema } from './manifest.js';
+} from './index.js';
+import { ManifestSchema, PkgManifestSchema } from '../manifest.js';
 
 const fullCaps: AgentCapabilities = {
   streaming: true,
@@ -203,3 +204,33 @@ test('AdapterLoader.load consumes a manifest carrying EngineProvides', () => {
   };
   assert.equal(input.engine.agentId, 'codex');
 });
+
+// ---------------- EngineNotImplementedError ----------------
+
+test('EngineNotImplementedError constructs cleanly with engineId only', () => {
+  const err = new EngineNotImplementedError('codex');
+  assert.equal(err.engineId, 'codex');
+  assert.equal(err.docsUrl, undefined);
+  assert.equal(err.message, 'Engine codex is not implemented yet');
+});
+
+test('EngineNotImplementedError constructs with docsUrl + custom message', () => {
+  const err = new EngineNotImplementedError('gemini', {
+    docsUrl: 'https://example.com/gemini-setup',
+    message: 'Gemini adapter is gated behind feature flag',
+  });
+  assert.equal(err.engineId, 'gemini');
+  assert.equal(err.docsUrl, 'https://example.com/gemini-setup');
+  assert.equal(err.message, 'Gemini adapter is gated behind feature flag');
+});
+
+test('EngineNotImplementedError is instanceof Error and EngineNotImplementedError', () => {
+  const err = new EngineNotImplementedError('aider');
+  assert.ok(err instanceof Error);
+  assert.ok(err instanceof EngineNotImplementedError);
+});
+
+test("EngineNotImplementedError.name is exactly 'EngineNotImplementedError'", () => {
+  const err = new EngineNotImplementedError('codex');
+  assert.equal(err.name, 'EngineNotImplementedError');
+});

package/src/engine/errors.ts

@@ -0,0 +1,20 @@
+/**
+ * Shared error types for engine adapters.
+ *
+ * Stub adapters (e.g. `engine-codex`, `engine-gemini`) detect a CLI on the
+ * host but don't yet implement `send` / `prompt`. They throw
+ * `EngineNotImplementedError` so the shell can render an actionable
+ * onboarding hint (the optional `docsUrl`) instead of a generic crash.
+ */
+
+export class EngineNotImplementedError extends Error {
+  readonly engineId: string;
+  readonly docsUrl?: string;
+
+  constructor(engineId: string, opts?: { docsUrl?: string; message?: string }) {
+    super(opts?.message ?? `Engine ${engineId} is not implemented yet`);
+    this.name = 'EngineNotImplementedError';
+    this.engineId = engineId;
+    this.docsUrl = opts?.docsUrl;
+  }
+}

package/src/engine/index.ts

@@ -0,0 +1,12 @@
+/**
+ * `@ikenga/contract/engine` — engine adapter surface.
+ *
+ * Exports BOTH the legacy `Engine` shape (`./adapter`) and the ACP-shaped
+ * surface (`./acp`) side-by-side for one deprecation cycle. Legacy types
+ * carry `@deprecated` JSDoc pointing at the ACP path. Shared error types
+ * live in `./errors`.
+ */
+
+export * from './adapter.js';
+export * from './acp.js';
+export * from './errors.js';

package/src/index.ts

@@ -1,6 +1,6 @@
 export * from './manifest.js';
 export * from './rpc.js';
-export * from './engine.js';
+export * from './engine/index.js';
 export * from './scopes.js';
 export * from './iyke.js';
 export * from './artifact.js';

package/src/manifest.ts

@@ -9,7 +9,7 @@
 // On disk: `<pkg-root>/manifest.json` (JSON, not TOML).
 
 import { z } from 'zod';
-import { EngineProvidesSchema } from './engine.js';
+import { EngineProvidesSchema } from './engine/index.js';
 
 export const IKENGA_API_VERSION = 1 as const;
 export const IKENGA_API_MIN_SUPPORTED = 1 as const;
@@ -28,6 +28,14 @@ export const McpServerSchema = z.object({
   env: z.record(z.string()).default({}),
   /** "per-call" (default) | "long-lived" */
   lifecycle: z.enum(['per-call', 'long-lived']).optional(),
+  /** Phase 9: glob patterns relative to pkg dir; supervisor restarts the
+   * long-lived child 250 ms after any matched file changes. Per-call entries
+   * ignore this. Empty = no watcher. */
+  restart_when_changed: z.array(z.string()).default([]),
+  /** Phase 9: auto-restart on unexpected exit. Default true (existing
+   * supervisor behavior). Set false for one-shot long-lived tools. Per-call
+   * entries ignore this. */
+  auto_restart: z.boolean().default(true),
 });
 export type McpServer = z.infer<typeof McpServerSchema>;
 
@@ -38,6 +46,12 @@ export const SidecarSpecSchema = z.object({
   bin: z.string(),
   /** "json" (default) | "raw" */
   stdio: z.string().default('json'),
+  /** Phase 9: glob patterns relative to pkg dir; supervisor restarts the
+   * sidecar 250 ms after any matched file changes. Empty = no watcher. */
+  restart_when_changed: z.array(z.string()).default([]),
+  /** Phase 9: auto-restart on unexpected exit. Default true (existing
+   * supervisor behavior). Set false for one-shot tools. */
+  auto_restart: z.boolean().default(true),
 });
 export type SidecarSpec = z.infer<typeof SidecarSpecSchema>;
 
@@ -133,6 +147,18 @@ export const QueriesBlockSchema = z.object({
   key_prefixes: z.array(z.string()).default([]),
 });
 
+/**
+ * UI preview screenshot. `path` is relative to the package's install_path
+ * for bundled pkgs; the shell resolves it to a webview-loadable URL on
+ * render. Registry pkgs surface absolute https:// URLs through the
+ * `screenshots` array on the registry entry (see `./registry.ts`).
+ */
+export const ScreenshotSchema = z.object({
+  path: z.string(),
+  caption: z.string().optional(),
+});
+export type Screenshot = z.infer<typeof ScreenshotSchema>;
+
 // ---------- Manifest ----------
 
 export const ManifestSchema = z.object({
@@ -171,6 +197,14 @@ export const ManifestSchema = z.object({
    * See `@ikenga/contract/engine` for the source-of-truth schema.
    */
   engine: EngineProvidesSchema.optional(),
+
+  /**
+   * Optional UI preview screenshots surfaced by the package manager and the
+   * install sheet. `path` is relative to the package's install_path; the
+   * shell mints a webview-loadable URL for it on render. Packages without
+   * UI (engines, MCP-only servers) typically leave this empty.
+   */
+  screenshots: z.array(ScreenshotSchema).default([]),
 });
 
 export type Manifest = z.infer<typeof ManifestSchema>;