@mxalbert/context-mode 2.0.0

package/build/adapters/opencode/plugin.d.ts

@@ -0,0 +1,249 @@
+/**
+ * OpenCode / KiloCode TypeScript plugin entry point for context-mode.
+ *
+ * Dual-flavor compatibility (opencode v1 + v2):
+ *   - v1 hosts load the plugin via `server(input)` (PluginModule default
+ *     export with shape `{ id, server }`).
+ *   - v2 hosts load the plugin via `setup(ctx)` on the default-export object
+ *     `{ id, server?, setup }` (v2 PluginModule shape).
+ *   Both entries live on the SAME default export object; each host picks the
+ *     entrypoint it supports. No `tui` marker is set (it would invalidate
+ *     server loading per the v2 migration guide).
+ *
+ * The v2 PluginContext surface is VERIFIED (opencode2 beta-19135 live probe
+ * + docs at opencode.ai/v2/docs/build/plugins): ctx.tool.transform(editor)
+ * registers native ctx_* tools (ToolEditor), ctx.tool.hook
+ * ("execute.before"/"execute.after") bridges routing enforcement + capture,
+ * ctx.session.hook("context"|"prompt") covers system-context injection
+ * (continuations AND compaction) and user-prompt capture, and
+ * ctx.event.subscribe() streams bus events. The v2 `setup` path probes each
+ * surface defensively (typeof checks; UNCONFIRMED payload fields are read
+ * defensively) and degrades HONESTLY — one-time log, never fake success.
+ * Mandatory for activation: native tool registration AND execute hooks;
+ * anything mandatory missing → no claim (MCP fallback stays intact); the
+ * session/event surfaces are optional and degrade with one-time logs.
+ *
+ * Hybrid-host guard: a process-global activation registry (keyed by plugin
+ * id + normalized project directory) ensures only ONE flavor activates per
+ * project per process. The second entrypoint (v1 server() or v2 setup())
+ * returns a noop/empty registration and logs once ("context-mode already
+ * active via <flavor>"). v1 claims if no claimant exists; v1 behavior is
+ * otherwise unchanged for existing users.
+ *
+ * Five hooks (v1.0.107 — Mickey OC-1..OC-4 follow-up):
+ *   - tool.execute.before  — Routing enforcement (deny/modify/passthrough)
+ *   - tool.execute.after   — Session event capture + first-fire AGENTS.md scan (OC-4)
+ *   - experimental.session.compacting — Compaction snapshot + budget-capped auto-injection (OC-3)
+ *   - experimental.chat.system.transform — ROUTING_BLOCK + resume snapshot injection (OC-1)
+ *   - chat.message         — User-prompt capture w/ CCv2 inline filter (OC-2) + AGENTS.md scan (OC-4)
+ *
+ * KiloCode loads this via: import("@mxalbert/context-mode") → expects default export
+ * with shape { server: (input) => Promise<Hooks> } (PluginModule).
+ *
+ * OpenCode loads this via: import("@mxalbert/context-mode/plugin") → also supports
+ * the named export ContextModePlugin for backward compat.
+ *
+ * Constraints:
+ *   - No SessionStart hook (OpenCode doesn't support it — #14808, #5409)
+ *   - context injection now via chat.system.transform surrogate (OC-1)
+ *   - No routing file auto-write (avoid dirtying project trees)
+ *   - Session cleanup happens at plugin init (no SessionStart)
+ */
+import { type PluginGlobalState } from "./index.js";
+import { type PluginClient, type V2SetupContext } from "./v2.js";
+type PluginContext = {
+    client: PluginClient;
+    directory: string;
+};
+type NativeToolContext = {
+    sessionID: string;
+    messageID: string;
+    agent: string;
+    directory: string;
+    worktree?: string;
+    abort?: AbortSignal;
+    metadata?: (input: {
+        title?: string;
+        metadata?: Record<string, unknown>;
+    }) => void;
+};
+type NativeToolDefinition = {
+    description: string;
+    args: Record<string, unknown>;
+    /**
+     * JSON-Schema view of the tool's Zod input schema (single shared
+     * conversion via zodSchemaToJsonSchema) — consumed by the v2 ToolEditor
+     * registration (ToolInfo.input). v1 hosts ignore this extra field.
+     */
+    inputJsonSchema?: Record<string, unknown>;
+    execute: (args: Record<string, unknown>, ctx: NativeToolContext) => Promise<string | {
+        title?: string;
+        output: string;
+        metadata?: Record<string, unknown>;
+    }>;
+};
+/** OpenCode tool.execute.before — first parameter */
+interface BeforeHookInput {
+    tool: string;
+    sessionID: string;
+    callID: string;
+}
+/** OpenCode tool.execute.before — second parameter */
+interface BeforeHookOutput {
+    args: any;
+}
+/** OpenCode tool.execute.after — first parameter */
+interface AfterHookInput {
+    tool: string;
+    sessionID: string;
+    callID: string;
+    args: any;
+}
+/** OpenCode tool.execute.after — second parameter */
+interface AfterHookOutput {
+    title: string;
+    output: string;
+    metadata: any;
+    /**
+     * Failure signal consumed by the shared capture handler. The v1 host
+     * never sets it (OpenCode doesn't provide isError — the response text
+     * alone drives error detection); the v2 execute.after bridge sets it on
+     * `status: "error"` so failed tool calls produce error_tool events via
+     * the SAME extractEvents path (extract.ts isToolError).
+     */
+    isError?: boolean;
+}
+/**
+ * OpenCode generic bus `event` hook — single parameter.
+ * The plugin SDK delivers every bus Event here (refs/platforms/opencode/
+ * packages/plugin/src/index.ts:224). We narrow to `message.updated`, whose
+ * `properties.info` is the full assistant Message carrying tokens/cost/modelID.
+ */
+interface EventHookInput {
+    event?: {
+        type?: string;
+        properties?: {
+            info?: {
+                sessionID?: string;
+            } & Record<string, unknown>;
+        };
+    };
+}
+/** OpenCode experimental.session.compacting — first parameter */
+interface CompactingHookInput {
+    sessionID: string;
+}
+/** OpenCode experimental.session.compacting — second parameter */
+interface CompactingHookOutput {
+    context: string[];
+    prompt?: string;
+}
+/**
+ * OpenCode experimental.chat.system.transform — first parameter.
+ * Verified against sst/opencode/dev/packages/plugin/src/index.ts:
+ *   input: { sessionID?: string; model: Model }
+ * `sessionID` is optional in the SDK type but is in practice always set
+ * (the transform runs *for* a session). We treat it as required and
+ * skip injection when absent rather than fall back to a fabricated ID.
+ *
+ * NOTE: We deliberately do NOT use `experimental.chat.messages.transform`.
+ * Its SDK input shape is `{}` (no sessionID) and its output is
+ * `{ messages: { info: Message; parts: Part[] }[] }` — the prior code
+ * (`output.messages.unshift({ role, content })`) wrote a value of the
+ * wrong shape and was silently dropped (Mickey / PR #376 root cause).
+ */
+interface SystemTransformHookInput {
+    sessionID?: string;
+    model: unknown;
+}
+/** OpenCode experimental.chat.system.transform — second parameter */
+interface SystemTransformHookOutput {
+    system: string[];
+}
+/**
+ * OpenCode chat.message hook — verified against
+ * refs/platforms/opencode/packages/plugin/src/index.ts:233.
+ *   input:  { sessionID; agent?; model?; messageID?; variant? }
+ *   output: { message: UserMessage; parts: Part[] }
+ * We read text from `parts[*].text` (the orchestrator reference at
+ * refs/plugin-examples/opencode/opencode-orchestrator/src/plugin-handlers/
+ * chat-message-handler.ts:41-65 uses the same pattern).
+ */
+interface ChatMessageHookInput {
+    sessionID: string;
+    agent?: string;
+    messageID?: string;
+}
+interface ChatMessagePart {
+    type: string;
+    text?: string;
+}
+interface ChatMessageHookOutput {
+    message: unknown;
+    parts: ChatMessagePart[];
+}
+declare const ROUTING_MARKERS: string[];
+declare function systemHasRoutingInstructions(system: string[]): boolean;
+/** Test-only: clear process-global activation + log-dedupe state. */
+export declare function __resetPluginStateForTests(): void;
+/** Test-only: expose the process-global state for assertions. */
+export declare function __getPluginGlobalState(): PluginGlobalState;
+/** Test-only: close the cached fd and clear the sink cache so each test gets a fresh sink. */
+export declare function __resetPluginLogSinkForTests(): void;
+/**
+ * Plugin factory. Called once when a v1 host (KiloCode/OpenCode ≤ v1) loads
+ * the plugin. Returns an object mapping hook event names to async handler
+ * functions over the shared runtime.
+ *
+ * Hybrid-host guard: if the v2 setup() path (or another v1 server() call)
+ * already claimed activation for this project, this returns an EMPTY
+ * registration — no hooks, no DB init — and logs once.
+ *
+ * KiloCode expects: export default { id: string, server: (input) => Promise<Hooks> }
+ * OpenCode expects: export const ContextModePlugin = (ctx) => Promise<Hooks>
+ */
+declare function createContextModePlugin(ctx: PluginContext): Promise<{
+    tool: {};
+    "tool.execute.before"?: undefined;
+    "tool.execute.after"?: undefined;
+    event?: undefined;
+    "chat.message"?: undefined;
+    "experimental.session.compacting"?: undefined;
+    "experimental.chat.system.transform"?: undefined;
+} | {
+    tool: Record<string, NativeToolDefinition>;
+    "tool.execute.before": (input: BeforeHookInput, output: BeforeHookOutput) => Promise<void>;
+    "tool.execute.after": (input: AfterHookInput, output: AfterHookOutput) => Promise<void>;
+    event: (input: EventHookInput) => Promise<void>;
+    "chat.message": (input: ChatMessageHookInput, output: ChatMessageHookOutput) => Promise<void>;
+    "experimental.session.compacting": (input: CompactingHookInput, output: CompactingHookOutput) => Promise<string>;
+    "experimental.chat.system.transform": (input: SystemTransformHookInput, output: SystemTransformHookOutput) => Promise<void>;
+}>;
+/**
+ * v2 plugin setup. Registers the v1-equivalent behaviors against whatever
+ * v2 surfaces the host exposes (runtime capability probing) and honors the
+ * hybrid-host activation guard.
+ *
+ * ACTIVATION POLICY: v2 may claim ONLY when the FULL mandatory surface
+ * succeeds — tool execute before/after hooks AND native ctx_* tool
+ * registration. If native tools cannot be registered, v2 does NOT claim
+ * (one-time degraded-reason log, MCP fallback retained) so a v1 server()
+ * entry can still claim for this project; on pure v2 hosts the same path
+ * yields honest degraded mode with mcp.context-mode retained. Optional
+ * capabilities (session context, event bus) degrade with one-time logs —
+ * never a fake success.
+ *
+ * Returns a cleanup function (where the host supports one) that unregisters
+ * everything registered, closes the runtime DB handle, and releases the
+ * activation claim so a plugin reload can re-claim without double-registering
+ * or leaking the old DB.
+ */
+declare function setupV2(ctx: V2SetupContext): Promise<(() => void) | void>;
+declare const _default: {
+    id: string;
+    server: typeof createContextModePlugin;
+    setup: typeof setupV2;
+};
+export default _default;
+export { createContextModePlugin as ContextModePlugin, setupV2 as ContextModeSetup };
+export { systemHasRoutingInstructions, ROUTING_MARKERS };