@retaw106/mmc-oc 0.0.0-stage → 1.2.2

package/src/shared/historian-tool-template.ts

@@ -0,0 +1,248 @@
+/** A deliberately non-executable language for readable, bounded historian tool lines. */
+export type ToolExpansionMap = Record<string, string | false>;
+type Step = { field: string } | { index: number } | { project: string };
+type Expression = {
+    steps: Step[];
+    each?: Template;
+    join?: string;
+    count?: boolean;
+    cap: number;
+};
+type Template = Array<string | Expression>;
+
+class Parser {
+    pos = 0;
+    constructor(private source: string) {}
+    error(): never {
+        throw new Error(`Invalid tool expansion template at character ${this.pos + 1}`);
+    }
+    take(value: string): boolean {
+        if (!this.source.startsWith(value, this.pos)) return false;
+        this.pos += value.length;
+        return true;
+    }
+    field(): string {
+        const match = /^[A-Za-z_][A-Za-z0-9_-]*/.exec(this.source.slice(this.pos));
+        if (!match) return this.error();
+        this.pos += match[0].length;
+        return match[0];
+    }
+    quoted(): string {
+        const start = this.pos;
+        if (!this.take('"')) return this.error();
+        while (this.pos < this.source.length) {
+            if (this.take("\\")) {
+                this.pos++;
+                continue;
+            }
+            if (this.take('"')) {
+                try {
+                    return JSON.parse(this.source.slice(start, this.pos));
+                } catch {
+                    return this.error();
+                }
+            }
+            this.pos++;
+        }
+        return this.error();
+    }
+    integer(): number {
+        const match = /^\d+/.exec(this.source.slice(this.pos));
+        if (!match) return this.error();
+        this.pos += match[0].length;
+        const n = Number(match[0]);
+        if (!Number.isSafeInteger(n)) return this.error();
+        return n;
+    }
+    expression(relative: boolean): Expression {
+        const steps: Step[] = [];
+        if (!(relative && this.take("."))) {
+            const root = this.field();
+            if (!relative && root !== "input" && root !== "output") return this.error();
+            steps.push({ field: root });
+        }
+        while (true) {
+            if (this.take("[")) {
+                if (this.take("*].")) steps.push({ project: this.field() });
+                else {
+                    const index = this.integer();
+                    if (!this.take("]")) return this.error();
+                    steps.push({ index });
+                }
+            } else if (
+                this.source[this.pos] === "." &&
+                !/^\.(each\(|join\(|count(?:\.|\})|truncate\()/.test(this.source.slice(this.pos))
+            ) {
+                this.pos++;
+                steps.push({ field: this.field() });
+                if (this.source[this.pos] === "(") return this.error();
+            } else break;
+        }
+        const expression: Expression = { steps, cap: 300 };
+        if (this.take(".each(")) {
+            if (relative) return this.error();
+            expression.each = parseTemplate(this.quoted(), true);
+            if (!this.take(")")) return this.error();
+        }
+        if (this.take(".join(")) {
+            expression.join = this.quoted();
+            if (!this.take(")")) return this.error();
+        }
+        if (this.take(".count")) {
+            if (expression.each || expression.join !== undefined) return this.error();
+            expression.count = true;
+        }
+        if (this.take(".truncate(")) {
+            expression.cap = this.integer();
+            if (!this.take(")")) return this.error();
+        }
+        if (!this.take("}")) return this.error();
+        return expression;
+    }
+    template(relative: boolean): Template {
+        const nodes: Template = [];
+        while (this.pos < this.source.length) {
+            const next = this.source.indexOf("${", this.pos);
+            if (next < 0) {
+                nodes.push(this.source.slice(this.pos));
+                break;
+            }
+            nodes.push(this.source.slice(this.pos, next));
+            this.pos = next + 2;
+            nodes.push(this.expression(relative));
+        }
+        return nodes;
+    }
+}
+
+function parseTemplate(source: string, relative = false): Template {
+    return new Parser(source).template(relative);
+}
+
+export function toolTemplateError(source: string): string | undefined {
+    try {
+        parseTemplate(source);
+        return undefined;
+    } catch (error) {
+        return (error as Error).message;
+    }
+}
+
+const templates = new Map<string, Template | null>();
+function compiled(source: string): Template | null {
+    if (!templates.has(source)) {
+        // Validation belongs to config loading. Malformed data from an older host
+        // must never interrupt a historian run.
+        try {
+            templates.set(source, parseTemplate(source));
+        } catch {
+            templates.set(source, null);
+        }
+    }
+    return templates.get(source) ?? null;
+}
+
+function oneLine(value: string): string {
+    return value.replace(/[\r\n\u2028\u2029]+/g, " ");
+}
+function truncate(value: string, cap: number): string {
+    const chars = Array.from(oneLine(value));
+    return chars.length > cap ? `${chars.slice(0, cap).join("")}…` : chars.join("");
+}
+function scalar(value: unknown): string {
+    if (value === undefined) return "";
+    return typeof value === "string" ? value : compactJson(value);
+}
+// Sort object keys so the two engines do not depend on their JSON map insertion order.
+function compactJson(value: unknown): string {
+    if (Array.isArray(value)) return `[${value.map((v) => compactJson(v)).join(",")}]`;
+    if (value !== null && typeof value === "object")
+        return `{${Object.keys(value)
+            .sort()
+            .map(
+                (key) =>
+                    `${JSON.stringify(key)}:${compactJson((value as Record<string, unknown>)[key])}`,
+            )
+            .join(",")}}`;
+    return JSON.stringify(value) ?? "null";
+}
+function field(value: unknown, key: string): unknown {
+    return value !== null &&
+        typeof value === "object" &&
+        !Array.isArray(value) &&
+        Object.hasOwn(value, key)
+        ? (value as Record<string, unknown>)[key]
+        : undefined;
+}
+function render(nodes: Template, root: unknown): string {
+    return nodes
+        .map((node) => {
+            if (typeof node === "string") return node;
+            let value = root;
+            let list = false;
+            for (const step of node.steps) {
+                if ("field" in step)
+                    value =
+                        list && Array.isArray(value)
+                            ? value.map((item) => field(item, step.field))
+                            : field(value, step.field);
+                else if ("index" in step)
+                    value = Array.isArray(value) ? value[step.index] : undefined;
+                else {
+                    value = Array.isArray(value)
+                        ? value.map((item) => field(item, step.project))
+                        : undefined;
+                    list = true;
+                }
+            }
+            if (node.count)
+                return truncate(Array.isArray(value) ? String(value.length) : "", node.cap);
+            if (node.each || list || node.join !== undefined) {
+                if (!Array.isArray(value)) return "";
+                const elements = value
+                    .slice(0, 10)
+                    .map((item) =>
+                        truncate(node.each ? render(node.each, item) : scalar(item), 300),
+                    );
+                if (value.length > 10) elements.push(`… +${value.length - 10} more`);
+                return truncate(elements.join(node.join ?? (node.each ? "; " : ", ")), node.cap);
+            }
+            return truncate(scalar(value), node.cap);
+        })
+        .join("");
+}
+
+export function renderToolTemplate(
+    source: string,
+    input: unknown,
+    output?: unknown,
+): string | null {
+    const nodes = compiled(source);
+    if (!nodes) return null;
+    const text =
+        typeof output === "string" ? output : output === undefined ? "" : compactJson(output);
+    let structured: unknown = output;
+    if (typeof output === "string") {
+        try {
+            const parsed = JSON.parse(output);
+            structured =
+                parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : undefined;
+        } catch {
+            structured = undefined;
+        }
+    }
+    // The bare output placeholder is the original result text, not reserialized JSON.
+    const root = { input, output: structured };
+    const bareOutputNodes = nodes.map((node) =>
+        typeof node !== "string" &&
+        node.steps.length === 1 &&
+        "field" in node.steps[0] &&
+        node.steps[0].field === "output" &&
+        !node.each &&
+        !node.count &&
+        node.join === undefined
+            ? truncate(text ?? "", node.cap)
+            : node,
+    );
+    return truncate(render(bareOutputNodes, root), 1000);
+}

package/src/shared/historian-transient-error.test.ts

@@ -0,0 +1,36 @@
+import { describe, expect, it } from "bun:test";
+
+import { isTransientHistorianPromptError } from "./historian-transient-error";
+
+describe("isTransientHistorianPromptError", () => {
+    it.each([
+        "429 rate limit from provider",
+        "rate_limit_error: slow down",
+        "503 Service Unavailable",
+        "502 Bad Gateway from upstream", // "bad gateway" is not "bad request"
+        "500 Internal Server Error",
+        "Overloaded",
+        "request timeout",
+        "read ECONNRESET",
+        "connect ETIMEDOUT",
+        "503 upstream author-profile service unavailable",
+    ])("retries %p", (message) => {
+        expect(isTransientHistorianPromptError(message)).toBe(true);
+    });
+
+    it.each([
+        "401 unauthorized",
+        "403 Forbidden",
+        "authentication_error: invalid x-api-key",
+        "OAuth token expired; 503",
+        "Authorization header missing (429)",
+        "400 Bad Request",
+        "status 400: malformed",
+        "invalid_request_error: prompt is too long: 250000 tokens > 200000 maximum",
+        "prompt is too long: 250000 tokens",
+        "request id 15003 failed",
+        "model not found",
+    ])("does not retry %p", (message) => {
+        expect(isTransientHistorianPromptError(message)).toBe(false);
+    });
+});

package/src/shared/historian-transient-error.ts

@@ -0,0 +1,22 @@
+/**
+ * Decide whether a failed historian prompt is worth retrying on the same model.
+ *
+ * Provider errors arrive as free text, so this is a keyword test, but every
+ * keyword must stand alone: "auth" must not match "author", and status 500
+ * must not match "250000" inside "prompt is too long: 250000 tokens". A
+ * misread here either retries a request that can never succeed (twice more,
+ * at full cost) or gives up on a provider blip.
+ *
+ * Shared by the OpenCode and Pi historian runners so both classify alike.
+ */
+const NON_TRANSIENT_PATTERN =
+    /(?<![a-z])(?:invalid[ _]request|bad[ _]request|unauthori[sz]ed|forbidden|authentication|authenticate|authorization|o?auth)(?![a-z])|(?:^| )400(?!\d)/;
+
+const TRANSIENT_PATTERN =
+    /(?<!\d)(?:429|500|502|503)(?!\d)|rate[ _]limit|timeout|econnreset|etimedout|overloaded/;
+
+export function isTransientHistorianPromptError(message: string): boolean {
+    const normalized = message.toLowerCase();
+    if (NON_TRANSIENT_PATTERN.test(normalized)) return false;
+    return TRANSIENT_PATTERN.test(normalized);
+}

package/src/shared/host-limitations.ts

@@ -0,0 +1,43 @@
+import { USER_FACING_FAILURES, type UserFacingFailureKey } from "./user-facing-codes";
+
+/**
+ * Named things the host Magic Context is running in cannot do.
+ *
+ * A limitation is not a failed operation: it is a capability the current host
+ * lacks for as long as this process lives, so every status surface keeps
+ * printing it instead of showing it once and forgetting. Each one is an
+ * existing MC-* user-facing code, so the status dialog, the plain-text status
+ * summary and the sidebar all print the same sentence for it.
+ *
+ * Process-global on purpose. The surfaces that show these (the RPC status and
+ * sidebar handlers) are built without a reference to the adapter that
+ * discovered the limitation, and a limitation of the host is true for every
+ * session in the process rather than for one of them.
+ */
+const declared = new Set<UserFacingFailureKey>();
+
+/**
+ * Record a limitation of this host. Returns true only the first time a given
+ * limitation is declared, which is what callers use to log their explanation
+ * once instead of on every pass.
+ */
+export function declareHostLimitation(key: UserFacingFailureKey): boolean {
+    if (declared.has(key)) return false;
+    declared.add(key);
+    return true;
+}
+
+/** Limitations declared so far, in the order they were first declared. */
+export function activeHostLimitations(): UserFacingFailureKey[] {
+    return [...declared];
+}
+
+/** The MC-* codes for the declared limitations, for logs and reports. */
+export function activeHostLimitationCodes(): string[] {
+    return activeHostLimitations().map((key) => USER_FACING_FAILURES[key].code);
+}
+
+/** Test helper: forget every declared limitation so suites do not leak them. */
+export function __resetHostLimitations(): void {
+    declared.clear();
+}

package/src/shared/index.ts

@@ -0,0 +1,7 @@
+export * from "./logger";
+export * from "./model-suggestion-retry";
+export * from "./normalize-sdk-response";
+export * from "./prompt-surface";
+export * from "./prompt-surface-runtime";
+export * from "./resolve-fallbacks";
+export * from "./summarize-child-stderr";

package/src/shared/internal-initiator-marker.ts

@@ -0,0 +1 @@
+export const OMO_INTERNAL_INITIATOR_MARKER = "<!-- OMO_INTERNAL_INITIATOR -->";