@mxalbert/context-mode 2.0.0

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

@@ -0,0 +1,117 @@
+/**
+ * adapters/opencode/v2 — self-contained OpenCode v2 helper machinery.
+ *
+ * Holds only what has a clean seam from the plugin orchestration in
+ * plugin.ts (which owns the shared v1 handlers, the v2 registration/
+ * bridging functions, setupV2, and the hybrid activation guard):
+ *   - the host-client log types (shared by the v1 and v2 logging paths)
+ *   - the VERIFIED v2 setup-context surface types (opencode2 beta-19135
+ *     live probe + docs build/plugins)
+ *   - the Zod → JSON-Schema converter feeding ToolInfo.input
+ *   - defensive field readers for the UNCONFIRMED v2 hook payload shapes
+ *
+ * Imports NOTHING from plugin.ts — no cycles. Exports kept minimal.
+ */
+export type PluginClientAppLogBodyExtra = {
+    sessionId?: string;
+    source?: string;
+};
+export type PluginClientAppLogBody = {
+    service: string;
+    level: "info" | "warn" | "error" | "debug";
+    message: string;
+    extra?: PluginClientAppLogBodyExtra;
+};
+export type PluginClientAppLogOptions = {
+    body: PluginClientAppLogBody;
+};
+export type PluginClientApp = {
+    log: (options: PluginClientAppLogOptions) => Promise<void>;
+};
+export type PluginClient = {
+    app: PluginClientApp;
+};
+/**
+ * VERIFIED against opencode2 beta-19135 (live probe) + the v2 plugin docs
+ * (opencode.ai/v2/docs/build/plugins):
+ *   ctx.tool  { reload, transform, hook }
+ *   ctx.session { hook, create, get, prompt, interrupt, rename, context, … }
+ *   ctx.event { subscribe }
+ *   ctx.app   { name, version, channel }   — NO app.log on v2
+ * Fields marked UNCONFIRMED (hook payload extras, event names) are accessed
+ * defensively — never assume a field exists.
+ */
+/** v2 ToolEditor — handed to the ctx.tool.transform callback. */
+export type V2ToolEditor = {
+    list?: () => unknown[];
+    get?: (id: string) => unknown;
+    namespace?: (options: unknown) => unknown;
+    add?: (tool: unknown) => unknown;
+    update?: (id: string, fn: (tool: unknown) => unknown) => unknown;
+    remove?: (id: string) => unknown;
+};
+/** v2 ToolInfo — what we register via editor.add() (docs: build/plugins). */
+export type V2ToolInfo = {
+    name: string;
+    description?: string;
+    /** JSON-Schema object schema for the tool input. */
+    input: Record<string, unknown>;
+    options?: {
+        namespace?: string;
+        codemode?: boolean;
+    };
+    execute: (input: unknown, tool: unknown) => Promise<unknown>;
+};
+export type V2SetupContext = {
+    directory?: string;
+    project?: {
+        directory?: string;
+    };
+    client?: PluginClient;
+    app?: {
+        name?: string;
+        version?: string;
+        channel?: string;
+    };
+    tool?: {
+        reload?: (...args: unknown[]) => unknown;
+        transform?: (cb: (editor: V2ToolEditor) => unknown) => unknown;
+        hook?: (name: string, cb: (event: unknown) => unknown) => unknown;
+    };
+    session?: {
+        hook?: (name: string, cb: (event: unknown) => unknown) => unknown;
+    };
+    event?: {
+        /** AsyncIterable of { type, ... } events; exact event shapes UNCONFIRMED. */
+        subscribe?: (options?: {
+            signal?: AbortSignal;
+        }) => unknown;
+    };
+};
+/**
+ * Convert a Zod (v3-classic) schema into a JSON-Schema object — the shared
+ * single conversion point for the v2 ToolInfo `input` field. The MCP layer
+ * passes its Zod schemas to the SDK (which converts internally), so there is
+ * no repo util to reuse; this helper covers exactly the constructs the
+ * ctx_* tools use (object/optional/default/enum/string/number/boolean/
+ * array/preprocess/record/union/literal/any) and degrades to a permissive
+ * `{}` (accept anything) for anything it does not understand — a weird
+ * schema must never break tool registration.
+ */
+export declare function zodSchemaToJsonSchema(schema: unknown, depth?: number): Record<string, unknown>;
+export declare function v2ToolNameOf(event: Record<string, any>): string;
+export declare function v2SessionIdOf(event: Record<string, any>): string;
+/**
+ * Extract displayable text from an UNCONFIRMED v2 tool-result shape
+ * ({content: "..."} | {content: [{text}]} | {output} | string | other).
+ */
+export declare function extractV2ToolResultText(result: unknown): string;
+/**
+ * Extract displayable text from an UNCONFIRMED v2 tool-error shape
+ * (Error | string | {message} | object | undefined). Feeds the shared
+ * post-tool capture on `execute.after` error status so failed tool calls
+ * still produce error_tool events (v1 parity — extract.ts isToolError).
+ */
+export declare function extractV2ToolErrorText(error: unknown): string;
+/** Read displayable text out of a v2 SystemPart (string or {text}). */
+export declare function v2SystemPartText(part: unknown): string;

package/build/adapters/opencode/v2.js

@@ -0,0 +1,224 @@
+/**
+ * adapters/opencode/v2 — self-contained OpenCode v2 helper machinery.
+ *
+ * Holds only what has a clean seam from the plugin orchestration in
+ * plugin.ts (which owns the shared v1 handlers, the v2 registration/
+ * bridging functions, setupV2, and the hybrid activation guard):
+ *   - the host-client log types (shared by the v1 and v2 logging paths)
+ *   - the VERIFIED v2 setup-context surface types (opencode2 beta-19135
+ *     live probe + docs build/plugins)
+ *   - the Zod → JSON-Schema converter feeding ToolInfo.input
+ *   - defensive field readers for the UNCONFIRMED v2 hook payload shapes
+ *
+ * Imports NOTHING from plugin.ts — no cycles. Exports kept minimal.
+ */
+// ── Zod → JSON-Schema (ToolInfo.input) ────────────────────
+/**
+ * Whether a Zod schema position is OMITTABLE for JSON-Schema `required`
+ * purposes. Unwraps wrapper constructs recursively:
+ *   ZodOptional → true (field may be absent)
+ *   ZodDefault → true (the default satisfies the field — omittable)
+ *   ZodEffects (z.preprocess/refine) → unwrap to the inner schema
+ *   ZodCatch → unwrap to the inner schema
+ *   ZodNullable → false (null allowed, but the field is still required —
+ *     matches zod-to-json-schema semantics)
+ */
+function zodSchemaIsOmittable(schema, depth = 0) {
+    if (depth > 12 || schema === null || typeof schema !== "object")
+        return false;
+    const def = schema._def;
+    if (!def)
+        return false;
+    switch (def.typeName) {
+        case "ZodOptional":
+            return true;
+        case "ZodDefault":
+            return true;
+        case "ZodCatch":
+            return zodSchemaIsOmittable(def.innerType, depth + 1);
+        case "ZodEffects":
+            return zodSchemaIsOmittable(def.schema, depth + 1);
+        case "ZodNullable":
+            return false;
+        default:
+            return false;
+    }
+}
+/**
+ * Convert a Zod (v3-classic) schema into a JSON-Schema object — the shared
+ * single conversion point for the v2 ToolInfo `input` field. The MCP layer
+ * passes its Zod schemas to the SDK (which converts internally), so there is
+ * no repo util to reuse; this helper covers exactly the constructs the
+ * ctx_* tools use (object/optional/default/enum/string/number/boolean/
+ * array/preprocess/record/union/literal/any) and degrades to a permissive
+ * `{}` (accept anything) for anything it does not understand — a weird
+ * schema must never break tool registration.
+ */
+export function zodSchemaToJsonSchema(schema, depth = 0) {
+    if (depth > 12 || schema === null || typeof schema !== "object")
+        return {};
+    try {
+        const def = schema._def ?? {};
+        const described = (out) => {
+            if (typeof def.description === "string" && def.description)
+                out.description = def.description;
+            return out;
+        };
+        switch (def.typeName) {
+            case "ZodString": {
+                const out = described({ type: "string" });
+                for (const check of Array.isArray(def.checks) ? def.checks : []) {
+                    if (check?.kind === "min" && typeof check.value === "number")
+                        out.minLength = check.value;
+                    if (check?.kind === "max" && typeof check.value === "number")
+                        out.maxLength = check.value;
+                }
+                return out;
+            }
+            case "ZodNumber":
+                return described({ type: "number" });
+            case "ZodBoolean":
+                return described({ type: "boolean" });
+            case "ZodEnum":
+                return described({ type: "string", enum: Array.isArray(def.values) ? def.values : [] });
+            case "ZodLiteral":
+                return described({ enum: [def.value] });
+            case "ZodArray":
+                return described({ type: "array", items: zodSchemaToJsonSchema(def.type, depth + 1) });
+            case "ZodRecord":
+                return described({ type: "object", additionalProperties: zodSchemaToJsonSchema(def.valueType, depth + 1) });
+            case "ZodUnion":
+                return described({ anyOf: (Array.isArray(def.options) ? def.options : []).map((o) => zodSchemaToJsonSchema(o, depth + 1)) });
+            case "ZodOptional":
+            case "ZodNullable":
+            case "ZodCatch":
+                return zodSchemaToJsonSchema(def.innerType, depth + 1);
+            case "ZodDefault": {
+                const out = zodSchemaToJsonSchema(def.innerType, depth + 1);
+                try {
+                    out.default = typeof def.defaultValue === "function" ? def.defaultValue() : def.defaultValue;
+                }
+                catch {
+                    // Non-computable default — omit it; the schema stays permissive.
+                }
+                return out;
+            }
+            case "ZodEffects":
+                // z.preprocess / refine / transform — the INNER schema is the
+                // contract; the coercion runs in the execute path (same as v1).
+                return zodSchemaToJsonSchema(def.schema, depth + 1);
+            case "ZodObject": {
+                const shape = typeof def.shape === "function"
+                    ? def.shape()
+                    : def.shape ?? {};
+                const properties = {};
+                const required = [];
+                for (const [key, value] of Object.entries(shape)) {
+                    properties[key] = zodSchemaToJsonSchema(value, depth + 1);
+                    // Requiredness sees through ZodOptional/ZodDefault/ZodEffects
+                    // (z.preprocess) wrappers — a defaulted or coerced-optional param
+                    // must stay omittable, otherwise HOST-side JSON-Schema validation
+                    // can reject the call before our Zod parse (with its coercions
+                    // and defaults) ever runs.
+                    if (!zodSchemaIsOmittable(value))
+                        required.push(key);
+                }
+                return described({ type: "object", properties, required });
+            }
+            case "ZodAny":
+            case "ZodUnknown":
+                return described({});
+            default:
+                // Unknown construct — permissive.
+                return described({});
+        }
+    }
+    catch {
+        return {};
+    }
+}
+// ── Defensive readers for UNCONFIRMED v2 hook payloads ────
+export function v2ToolNameOf(event) {
+    if (typeof event.tool === "string")
+        return event.tool;
+    if (event.tool && typeof event.tool === "object") {
+        const t = event.tool;
+        if (typeof t.name === "string")
+            return t.name;
+        if (typeof t.id === "string")
+            return t.id;
+    }
+    return "";
+}
+export function v2SessionIdOf(event) {
+    const candidate = event.sessionID ??
+        event.session?.id ??
+        event.tool?.sessionID ??
+        event.input?.sessionID ??
+        event.metadata?.sessionID;
+    return typeof candidate === "string" && candidate ? candidate : "";
+}
+/**
+ * Extract displayable text from an UNCONFIRMED v2 tool-result shape
+ * ({content: "..."} | {content: [{text}]} | {output} | string | other).
+ */
+export function extractV2ToolResultText(result) {
+    if (typeof result === "string")
+        return result;
+    if (result === null || typeof result !== "object")
+        return "";
+    const r = result;
+    if (typeof r.content === "string")
+        return r.content;
+    if (Array.isArray(r.content)) {
+        return r.content
+            .map((part) => (part && typeof part === "object" && typeof part.text === "string" ? part.text : ""))
+            .filter(Boolean)
+            .join("\n");
+    }
+    if (typeof r.output === "string")
+        return r.output;
+    try {
+        return JSON.stringify(r);
+    }
+    catch {
+        return String(result);
+    }
+}
+/**
+ * Extract displayable text from an UNCONFIRMED v2 tool-error shape
+ * (Error | string | {message} | object | undefined). Feeds the shared
+ * post-tool capture on `execute.after` error status so failed tool calls
+ * still produce error_tool events (v1 parity — extract.ts isToolError).
+ */
+export function extractV2ToolErrorText(error) {
+    if (typeof error === "string")
+        return error;
+    if (error instanceof Error) {
+        const code = error.code;
+        return code ? `${error.message} (code=${code})` : error.message;
+    }
+    if (error !== null && typeof error === "object") {
+        const e = error;
+        if (typeof e.message === "string" && e.message)
+            return e.message;
+        try {
+            return JSON.stringify(e);
+        }
+        catch {
+            // fall through to String
+        }
+    }
+    return error !== undefined && error !== null ? String(error) : "tool execute failed";
+}
+/** Read displayable text out of a v2 SystemPart (string or {text}). */
+export function v2SystemPartText(part) {
+    if (typeof part === "string")
+        return part;
+    if (part !== null && typeof part === "object") {
+        const text = part.text;
+        if (typeof text === "string")
+            return text;
+    }
+    return "";
+}

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

@@ -0,0 +1 @@
+export declare function zod3ShapeToV4(shape: Record<string, unknown>, depth?: number): Record<string, unknown>;

package/build/adapters/opencode/zod3tov4.js

@@ -0,0 +1,132 @@
+/**
+ * Zod 3 → Zod 4 shape conversion for in-process plugin hosts that bundle Zod v4.
+ *
+ * KiloCode (since its inception) and recent OpenCode releases (≥ ~1.14.x)
+ * bundle Zod v4 internally. When they receive plugin tool definitions whose
+ * `args` contain Zod v3 schemas (with `_def` but no `_zod.def`), they crash
+ * with `TypeError: undefined is not an object (evaluating 'n._zod.def')`.
+ *
+ * This module converts Zod 3 schema shapes into Zod 4 equivalents so both
+ * hosts can process them natively.
+ */
+import z from 'zod/v4';
+export function zod3ShapeToV4(shape, depth = 0) {
+    const result = {};
+    for (const [key, value] of Object.entries(shape)) {
+        result[key] = zod3ToV4(value, depth);
+    }
+    return result;
+}
+function zod3ToV4(v, depth = 0) {
+    if (depth > 10)
+        return z.unknown();
+    if (v == null || typeof v !== "object")
+        return z.unknown();
+    const obj = v;
+    if (!obj._def || typeof obj._def !== "object")
+        return z.unknown();
+    const def = obj._def;
+    let result;
+    switch (def.typeName) {
+        case "ZodString":
+            result = def.coerce === true ? z.coerce.string() : z.string();
+            break;
+        case "ZodNumber":
+            result = def.coerce === true ? z.coerce.number() : z.number();
+            break;
+        case "ZodBoolean":
+            result = def.coerce === true ? z.coerce.boolean() : z.boolean();
+            break;
+        case "ZodAny":
+            result = z.any();
+            break;
+        case "ZodUnknown":
+            result = z.unknown();
+            break;
+        case "ZodNever":
+            result = z.never();
+            break;
+        case "ZodNull":
+            result = z.null();
+            break;
+        case "ZodUndefined":
+            result = z.undefined();
+            break;
+        case "ZodLiteral":
+            result = z.literal(def.value);
+            break;
+        case "ZodArray":
+            result = z.array(zod3ToV4(def.type ?? def.elementType, depth + 1));
+            break;
+        case "ZodEnum": {
+            const values = def.values;
+            result = Array.isArray(values) && values.length > 0
+                ? z.enum(values)
+                : z.never();
+            break;
+        }
+        case "ZodObject": {
+            const raw = def.shape;
+            const inner = typeof raw === "function" ? raw() : raw;
+            result = z.object(inner ? zod3ShapeToV4(inner, depth + 1) : {});
+            break;
+        }
+        case "ZodOptional":
+            result = z.optional(zod3ToV4(def.innerType ?? def.type, depth + 1));
+            break;
+        case "ZodNullable":
+            result = z.nullable(zod3ToV4(def.innerType ?? def.type, depth + 1));
+            break;
+        case "ZodDefault": {
+            const val = typeof def.defaultValue === "function"
+                ? def.defaultValue()
+                : def.defaultValue;
+            result = zod3ToV4(def.innerType ?? def.type, depth + 1).default(val);
+            break;
+        }
+        case "ZodRecord":
+            result = z.record(z.string(), zod3ToV4(def.valueType, depth + 1));
+            break;
+        case "ZodUnion": {
+            const opts = def.options;
+            if (!opts || opts.length === 0)
+                return z.never();
+            if (opts.length === 1)
+                return zod3ToV4(opts[0], depth + 1);
+            result = z.union(opts.map(o => zod3ToV4(o, depth + 1)));
+            break;
+        }
+        case "ZodEffects": {
+            // Zod v3 has two patterns for coercion:
+            //
+            // 1. Native coercion (z.coerce.number()): typeName is ZodNumber
+            //    with _def.coerce=true. Handled in the ZodNumber case above.
+            //
+            // 2. Custom preprocess (z.preprocess(fn, schema)): typeName is
+            //    ZodEffects with effect.type="preprocess". The transform is
+            //    plain JS and works identically in Zod v4's z.preprocess().
+            //
+            // We never map ZodEffects→native coerce here because native
+            // coerce is already a ZodType (not ZodEffects), and custom
+            // transforms can't be safely replaced (e.g., z.coerce.boolean()
+            // in v4 converts "false"→true via Boolean(), which is wrong).
+            const effect = def.effect;
+            if (effect?.type === "preprocess" && typeof effect?.transform === "function") {
+                const innerSchema = zod3ToV4(def.schema, depth + 1);
+                result = z.preprocess(effect.transform, innerSchema);
+            }
+            else {
+                // Refinement / transform effects — host schema only.
+                result = zod3ToV4(def.schema, depth + 1);
+            }
+            break;
+        }
+        default:
+            // Never leak raw Zod 3 schemas back to a v4 host.
+            result = z.unknown();
+            break;
+    }
+    return def.description && typeof result.describe === "function"
+        ? result.describe(String(def.description))
+        : result;
+}

package/build/adapters/pi/extension.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Pi coding agent extension for context-mode.
+ *
+ * Follows the OpenClaw adapter pattern: imports shared session modules,
+ * registers Pi-specific hooks. NO copy-paste of session logic.
+ * NO external npm dependencies beyond what Pi runtime provides.
+ *
+ * Entry point: `export default function(pi: ExtensionAPI) { ... }`
+ *
+ * Lifecycle: session_start, tool_call, tool_result, before_agent_start,
+ * session_before_compact, session_compact, session_shutdown.
+ */
+/**
+ * Strip heredoc + single-quoted + double-quoted content from a shell command
+ * so the routing regex only sees command tokens, not user-provided strings.
+ *
+ * Mirrors hooks/core/routing.mjs:196–209. Inlined here because the Pi
+ * extension is bundled as a standalone build artifact (.pi/extensions/...)
+ * and cannot import hooks/core/* at runtime — they live in a sibling tree
+ * and may not be present in every Pi installation.
+ *
+ * Exported for unit tests.
+ */
+export declare function stripQuotedContent(cmd: string): string;
+/**
+ * Returns true iff `segment` is a curl/wget invocation that is SAFE to allow
+ * through the Pi routing block — i.e. it cannot flood the model's context
+ * window because the response body is written to disk (or appended to a file)
+ * and no verbose/trace flag is dumping headers to stderr.
+ *
+ * Mirrors hooks/core/routing.mjs:672–701. Segments that are NOT curl/wget
+ * return `true` (nothing to evaluate). The caller is expected to split chained
+ * commands on `&&`, `||`, `;` and call this per segment.
+ *
+ * Issue #625 — without this, the only escape hatch when the MCP bridge dies
+ * is `gh` CLI or a full Pi restart. Neither is acceptable as baseline UX.
+ *
+ * Exported for unit tests.
+ */
+export declare function isSafeCurlWget(segment: string): boolean;
+/**
+ * Settles when the MCP bridge bootstrap has finished — resolves on
+ * success AND on failure (the bootstrap is best-effort; failures are
+ * logged to stderr but never propagated). Exposed for tests so they
+ * can `await` the wiring deterministically without relying on internal
+ * timing or `setImmediate` polling.
+ *
+ * Starts as an already-settled promise because the bridge is now bootstrapped
+ * lazily from `before_agent_start`, not during extension discovery.
+ */
+export declare let _mcpBridgeReady: Promise<void>;
+/**
+ * Issue #545 — Pi workspace resolver.
+ *
+ * Pi's runtime sets PI_CONFIG_DIR to ~/.pi (its CONFIG dir, not the user's
+ * project). The extension previously used this as the project anchor, which
+ * meant every Pi session re-rooted under ~/.pi — collapsing all of a user's
+ * projects into a single phantom workspace. This helper picks the user's
+ * actual project directory while NEVER returning a path equal to or under
+ * ~/.pi/.
+ *
+ * Cascade:
+ *   1. PI_WORKSPACE_DIR — set by Pi's bridge (extension-set, freshest)
+ *   2. PI_PROJECT_DIR   — legacy/user override
+ *   3. PWD              — shell-set, survives process.chdir
+ *   4. cwd              — last resort
+ *
+ * Each candidate is rejected if it equals ~/.pi or lives under ~/.pi/. If
+ * every candidate is poisoned, falls back to homedir() as a safe non-config
+ * anchor — caller may still render a "no project context" notice but the
+ * function stays total.
+ */
+export declare function resolvePiWorkspaceDir(opts: {
+    env: Record<string, string | undefined>;
+    pwd: string | undefined;
+    cwd: string;
+    /** Optional override for tests; defaults to `os.homedir()`. */
+    home?: string;
+}): string;
+/** Pi extension default export. Called once by Pi runtime with the extension API. */
+export default function piExtension(pi: any): void;