@jterrats/open-orchestra 0.1.0 → 0.2.1

package/dist/instruction-blocks.js

@@ -0,0 +1,120 @@
+import { createHash } from "node:crypto";
+import { readFile, writeFile } from "node:fs/promises";
+const START_PATTERN = /<!-- open-orchestra:start ([^>]+) -->/g;
+const END_PREFIX = '<!-- open-orchestra:end block-id="';
+export function renderManagedInstructionBlock(input) {
+    const hash = hashContent(input.content);
+    const updatedAt = input.updatedAt ?? new Date().toISOString();
+    return [
+        `<!-- open-orchestra:start block-id="${input.blockId}" generator="${input.generator}" version="${input.version}" target="${input.target}" source-manifest="${input.sourceManifest}" content-sha256="${hash}" updated-at="${updatedAt}" -->`,
+        input.content.trimEnd(),
+        `<!-- open-orchestra:end block-id="${input.blockId}" -->`,
+        "",
+    ].join("\n");
+}
+export function upsertManagedInstructionBlock(existing, input, options = {}) {
+    const hash = hashContent(input.content);
+    const range = findManagedBlock(existing, input.blockId);
+    const rendered = renderManagedInstructionBlock({
+        ...input,
+        updatedAt: stableInstructionUpdatedAt(range, hash, input.updatedAt),
+    });
+    if (!range) {
+        const separator = existing.trim() === "" ? "" : existing.endsWith("\n") ? "\n" : "\n\n";
+        return {
+            content: `${existing}${separator}${rendered}`,
+            changed: true,
+            drift: false,
+            missing: true,
+            hash,
+        };
+    }
+    const drift = range.actualHash !== range.metadataHash;
+    if (drift && !options.force) {
+        return {
+            content: existing,
+            changed: false,
+            drift: true,
+            missing: false,
+            hash,
+            existingHash: range.metadataHash,
+        };
+    }
+    const content = existing.slice(0, range.start) + rendered + existing.slice(range.end);
+    return {
+        content,
+        changed: content !== existing,
+        drift,
+        missing: false,
+        hash,
+        existingHash: range.metadataHash,
+    };
+}
+export function checkManagedInstructionBlock(existing, input) {
+    const result = upsertManagedInstructionBlock(existing, input);
+    return { ...result, content: existing };
+}
+export async function updateManagedInstructionFile({ filePath, contentPath, input, check = false, dryRun = false, force = false, }) {
+    const [existing, content] = await Promise.all([
+        readFile(filePath, "utf8").catch(() => ""),
+        readFile(contentPath, "utf8"),
+    ]);
+    const blockInput = { ...input, content };
+    const result = check
+        ? checkManagedInstructionBlock(existing, blockInput)
+        : upsertManagedInstructionBlock(existing, blockInput, { force });
+    if (!check && !dryRun && !result.drift && result.changed) {
+        await writeFile(filePath, result.content);
+    }
+    return result;
+}
+export function findManagedBlock(existing, blockId) {
+    START_PATTERN.lastIndex = 0;
+    let match;
+    while ((match = START_PATTERN.exec(existing))) {
+        const attributes = parseAttributes(match[1] ?? "");
+        if (attributes.get("block-id") !== blockId) {
+            continue;
+        }
+        const endMarker = `${END_PREFIX}${blockId}" -->`;
+        const contentStart = match.index + match[0].length + 1;
+        const endStart = existing.indexOf(endMarker, contentStart);
+        if (endStart === -1) {
+            throw new Error(`managed block ${blockId} is missing its end marker`);
+        }
+        const afterEnd = endStart + endMarker.length;
+        const managedContent = existing.slice(contentStart, endStart).trimEnd();
+        return {
+            start: match.index,
+            end: existing[afterEnd] === "\n" ? afterEnd + 1 : afterEnd,
+            metadataHash: attributes.get("content-sha256") ?? "",
+            actualHash: hashContent(managedContent),
+            attributes,
+        };
+    }
+    return null;
+}
+function stableInstructionUpdatedAt(range, nextHash, requestedUpdatedAt) {
+    if (requestedUpdatedAt) {
+        return requestedUpdatedAt;
+    }
+    if (range?.metadataHash === nextHash) {
+        return range.attributes.get("updated-at") ?? new Date().toISOString();
+    }
+    return new Date().toISOString();
+}
+function parseAttributes(value) {
+    const attributes = new Map();
+    for (const match of value.matchAll(/([a-z0-9-]+)="([^"]*)"/g)) {
+        const key = match[1];
+        const attributeValue = match[2];
+        if (key !== undefined && attributeValue !== undefined) {
+            attributes.set(key, attributeValue);
+        }
+    }
+    return attributes;
+}
+export function hashContent(content) {
+    return createHash("sha256").update(content.trimEnd()).digest("hex");
+}
+//# sourceMappingURL=instruction-blocks.js.map

package/dist/instruction-blocks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"instruction-blocks.js","sourceRoot":"","sources":["../src/instruction-blocks.ts"],"names":[],"mappings":"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"}

package/dist/instruction-imports.d.ts

@@ -0,0 +1,12 @@
+import type { InstructionImportEntry, InstructionImportResolution, InstructionTarget } from "./instruction-types.js";
+export declare function parseInstructionImports(content: string): string[];
+export declare function resolveInstructionImports({ entryId, entries, target, }: {
+    entryId: string;
+    entries: InstructionImportEntry[];
+    target: InstructionTarget;
+}): InstructionImportResolution;
+export declare function resolveInstructionImportsFromFile({ registryPath, entryId, target, }: {
+    registryPath: string;
+    entryId: string;
+    target: InstructionTarget;
+}): Promise<InstructionImportResolution>;

package/dist/instruction-imports.js

@@ -0,0 +1,45 @@
+import { readFile } from "node:fs/promises";
+const IMPORT_PATTERN = /^\s*@orchestra\/import\s+([a-zA-Z0-9._-]+)\s*$/;
+export function parseInstructionImports(content) {
+    return content
+        .split("\n")
+        .map((line) => line.match(IMPORT_PATTERN)?.[1])
+        .filter((value) => Boolean(value));
+}
+export function resolveInstructionImports({ entryId, entries, target, }) {
+    const registry = new Map(entries.map((entry) => [entry.id, entry]));
+    const importedIds = [];
+    const visiting = new Set();
+    const visited = new Set();
+    const content = resolveEntry(entryId, registry, target, visiting, visited, importedIds);
+    return { entryId, target, content, importedIds };
+}
+export async function resolveInstructionImportsFromFile({ registryPath, entryId, target, }) {
+    const entries = JSON.parse(await readFile(registryPath, "utf8"));
+    return resolveInstructionImports({ entryId, entries, target });
+}
+function resolveEntry(entryId, registry, target, visiting, visited, importedIds) {
+    const entry = registry.get(entryId);
+    if (!entry) {
+        throw new Error(`missing instruction import: ${entryId}`);
+    }
+    if (visiting.has(entryId)) {
+        throw new Error(`cyclic instruction import: ${Array.from(visiting).concat(entryId).join(" -> ")}`);
+    }
+    const raw = entry.targets?.[target] ?? entry.content;
+    visiting.add(entryId);
+    const lines = raw.split("\n").flatMap((line) => {
+        const imported = line.match(IMPORT_PATTERN)?.[1];
+        if (!imported) {
+            return [line];
+        }
+        if (!visited.has(imported)) {
+            importedIds.push(imported);
+        }
+        return resolveEntry(imported, registry, target, visiting, visited, importedIds).split("\n");
+    });
+    visiting.delete(entryId);
+    visited.add(entryId);
+    return lines.join("\n");
+}
+//# sourceMappingURL=instruction-imports.js.map

package/dist/instruction-imports.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"instruction-imports.js","sourceRoot":"","sources":["../src/instruction-imports.ts"],"names":[],"mappings":"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"}

package/dist/instruction-stale.d.ts

@@ -0,0 +1,9 @@
+import type { InstructionFileSpec, InstructionFileStatusReport } from "./instruction-types.js";
+export declare function detectStaleInstructionFiles({ root, specs, }: {
+    root?: string;
+    specs: InstructionFileSpec[];
+}): Promise<InstructionFileStatusReport>;
+export declare function detectStaleInstructionFilesFromManifest({ root, manifestPath, }: {
+    root?: string;
+    manifestPath: string;
+}): Promise<InstructionFileStatusReport>;

package/dist/instruction-stale.js

@@ -0,0 +1,106 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { findManagedBlock, hashContent } from "./instruction-blocks.js";
+export async function detectStaleInstructionFiles({ root = process.cwd(), specs, }) {
+    const items = [];
+    for (const spec of specs) {
+        items.push(await inspectInstructionFile(root, spec));
+    }
+    return { items, totals: summarizeInstructionStatuses(items) };
+}
+export async function detectStaleInstructionFilesFromManifest({ root = process.cwd(), manifestPath, }) {
+    const manifest = JSON.parse(await readFile(manifestPath, "utf8"));
+    return detectStaleInstructionFiles({ root, specs: manifest.files ?? [] });
+}
+async function inspectInstructionFile(root, spec) {
+    const expectedHash = hashContent(spec.content);
+    const resolvedPath = path.resolve(root, spec.filePath);
+    let existing;
+    try {
+        existing = await readFile(resolvedPath, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            return {
+                filePath: spec.filePath,
+                blockId: spec.blockId,
+                status: "missing",
+                expectedHash,
+                reason: "file does not exist",
+            };
+        }
+        throw error;
+    }
+    const block = findManagedBlock(existing, spec.blockId);
+    if (!block) {
+        return {
+            filePath: spec.filePath,
+            blockId: spec.blockId,
+            status: existing.includes("open-orchestra:start")
+                ? "missing"
+                : "user-owned",
+            expectedHash,
+            reason: existing.includes("open-orchestra:start")
+                ? "managed block is missing from generated file"
+                : "file has no Open Orchestra managed marker",
+        };
+    }
+    const common = removeUndefinedInstructionStatus({
+        filePath: spec.filePath,
+        blockId: spec.blockId,
+        expectedHash,
+        actualHash: block.actualHash,
+        metadataHash: block.metadataHash,
+        generator: block.attributes.get("generator"),
+        version: block.attributes.get("version"),
+        target: block.attributes.get("target"),
+        sourceManifest: block.attributes.get("source-manifest"),
+        updatedAt: block.attributes.get("updated-at"),
+    });
+    if (block.actualHash !== block.metadataHash) {
+        return {
+            ...common,
+            status: "drifted",
+            reason: "managed block content was edited manually",
+        };
+    }
+    if (block.metadataHash !== expectedHash) {
+        return {
+            ...common,
+            status: "stale",
+            reason: "managed block hash differs from current source",
+        };
+    }
+    if (common.generator !== spec.generator ||
+        common.version !== spec.version ||
+        common.target !== spec.target ||
+        common.sourceManifest !== spec.sourceManifest) {
+        return {
+            ...common,
+            status: "stale",
+            reason: "managed block metadata differs from current manifest",
+        };
+    }
+    return {
+        ...common,
+        status: "fresh",
+        reason: "managed block matches current source",
+    };
+}
+function removeUndefinedInstructionStatus(value) {
+    return Object.fromEntries(Object.entries(value).filter((entry) => entry[1] !== undefined));
+}
+function summarizeInstructionStatuses(items) {
+    const totals = {
+        fresh: 0,
+        stale: 0,
+        drifted: 0,
+        missing: 0,
+        "user-owned": 0,
+    };
+    for (const item of items) {
+        totals[item.status] += 1;
+    }
+    return totals;
+}
+//# sourceMappingURL=instruction-stale.js.map

package/dist/instruction-stale.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"instruction-stale.js","sourceRoot":"","sources":["../src/instruction-stale.ts"],"names":[],"mappings":"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"}

package/dist/instruction-types.d.ts

@@ -0,0 +1,66 @@
+export type InstructionTarget = "generic" | "claude" | "cursor" | "codex" | "vscode" | "windsurf";
+export type InstructionFileStatus = "fresh" | "stale" | "drifted" | "missing" | "user-owned";
+export interface InstructionFileSpec {
+    filePath: string;
+    blockId: string;
+    generator: string;
+    version: string;
+    target: InstructionTarget;
+    sourceManifest: string;
+    content: string;
+}
+export interface InstructionFileMetadata {
+    blockId: string;
+    generator: string;
+    version: string;
+    target: InstructionTarget;
+    sourceManifest: string;
+    contentHash: string;
+    updatedAt: string;
+}
+export interface InstructionFileStatusItem {
+    filePath: string;
+    blockId: string;
+    status: InstructionFileStatus;
+    expectedHash: string;
+    actualHash?: string;
+    metadataHash?: string;
+    generator?: string;
+    version?: string;
+    target?: string;
+    sourceManifest?: string;
+    updatedAt?: string;
+    reason: string;
+}
+export interface InstructionFileStatusReport {
+    items: InstructionFileStatusItem[];
+    totals: Record<InstructionFileStatus, number>;
+}
+export interface ManagedInstructionBlockInput {
+    blockId: string;
+    generator: string;
+    version: string;
+    target: InstructionTarget;
+    sourceManifest: string;
+    content: string;
+    updatedAt?: string;
+}
+export interface ManagedInstructionBlockResult {
+    content: string;
+    changed: boolean;
+    drift: boolean;
+    missing: boolean;
+    hash: string;
+    existingHash?: string;
+}
+export interface InstructionImportEntry {
+    id: string;
+    content: string;
+    targets?: Partial<Record<InstructionTarget, string>>;
+}
+export interface InstructionImportResolution {
+    entryId: string;
+    target: InstructionTarget;
+    content: string;
+    importedIds: string[];
+}

package/dist/instruction-types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=instruction-types.js.map

package/dist/instruction-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"instruction-types.js","sourceRoot":"","sources":["../src/instruction-types.ts"],"names":[],"mappings":""}

package/dist/instruction-updates.d.ts

@@ -0,0 +1,4 @@
+export * from "./instruction-types.js";
+export * from "./instruction-blocks.js";
+export * from "./instruction-imports.js";
+export * from "./instruction-stale.js";

package/dist/instruction-updates.js

@@ -0,0 +1,5 @@
+export * from "./instruction-types.js";
+export * from "./instruction-blocks.js";
+export * from "./instruction-imports.js";
+export * from "./instruction-stale.js";
+//# sourceMappingURL=instruction-updates.js.map

package/dist/instruction-updates.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"instruction-updates.js","sourceRoot":"","sources":["../src/instruction-updates.ts"],"names":[],"mappings":"AAAA,cAAc,wBAAwB,CAAC;AACvC,cAAc,yBAAyB,CAAC;AACxC,cAAc,0BAA0B,CAAC;AACzC,cAAc,wBAAwB,CAAC"}

package/dist/knowledge-base.d.ts

@@ -0,0 +1,10 @@
+export interface SourceOfTruthEntry {
+    id: string;
+    name: string;
+    description: string;
+    priority: number;
+    locations: string[];
+    useWhen: string[];
+    verification: string;
+}
+export declare function defaultSourceOfTruthCatalog(): SourceOfTruthEntry[];

package/dist/knowledge-base.js

@@ -0,0 +1,117 @@
+export function defaultSourceOfTruthCatalog() {
+    return [
+        {
+            id: "project-instructions",
+            name: "Project Instructions",
+            description: "Always-loaded project instructions and local agent operating rules.",
+            priority: 1,
+            locations: ["AGENTS.md", "ORCHESTRA.md", "CLAUDE.md", "rules/*.mdc"],
+            useWhen: [
+                "before planning",
+                "before implementation",
+                "before final response",
+            ],
+            verification: "Prefer the most specific local instruction file for the current tool or agent.",
+        },
+        {
+            id: "product-backlog",
+            name: "Product Backlog",
+            description: "User stories, acceptance criteria, tasks, and workflow state.",
+            priority: 2,
+            locations: [
+                "docs/multi-agent-orchestrator-backlog.md",
+                ".agent-workflow/tasks.json",
+                "GitHub issues",
+            ],
+            useWhen: ["before scope decisions", "before implementation", "before QA"],
+            verification: "Confirm the backlog item and acceptance criteria before starting work.",
+        },
+        {
+            id: "architecture",
+            name: "Architecture and Design",
+            description: "Architecture docs, ADRs, diagrams, service boundaries, and integration contracts.",
+            priority: 3,
+            locations: [
+                "docs/*.md",
+                ".agent-workflow/decisions/",
+                ".generated-prompts/diagrams.md",
+            ],
+            useWhen: ["before non-trivial design", "before cross-module changes"],
+            verification: "Record architecture conflicts as decisions or blockers.",
+        },
+        {
+            id: "codebase",
+            name: "Codebase",
+            description: "Source code, tests, package manifests, config, and local command contracts.",
+            priority: 4,
+            locations: ["src/", "test/", "package.json", "tsconfig.json"],
+            useWhen: ["before code changes", "before refactors", "before tests"],
+            verification: "Inspect existing patterns before adding new abstractions or dependencies.",
+        },
+        {
+            id: "quality-security",
+            name: "Quality and Security",
+            description: "Static analysis, hooks, scans, QA plans, and test evidence.",
+            priority: 5,
+            locations: [
+                ".githooks/",
+                ".agent-workflow/evidence/",
+                "test/",
+                "playwright.config.*",
+            ],
+            useWhen: ["before commit", "before release", "before risk review"],
+            verification: "Use local commands and evidence artifacts as proof, not generated explanations.",
+        },
+        {
+            id: "devops-runtime",
+            name: "DevOps and Runtime",
+            description: "CI/CD, deployment, IaC, observability, rollback, and release artifacts.",
+            priority: 6,
+            locations: [
+                ".github/workflows/",
+                "infra/",
+                "docs/*release*.md",
+                "docs/*runbook*.md",
+            ],
+            useWhen: [
+                "before workflow changes",
+                "before deploy",
+                "before release readiness",
+            ],
+            verification: "Validate downtime, rollback, secrets, environment isolation, and observability impact.",
+        },
+        {
+            id: "vendor-docs",
+            name: "Official Vendor Documentation",
+            description: "Official provider, framework, package, cloud, and browser documentation.",
+            priority: 7,
+            locations: ["official documentation URLs recorded by task"],
+            useWhen: [
+                "current APIs",
+                "provider behavior",
+                "framework behavior",
+                "cloud/runtime behavior",
+            ],
+            verification: "Use primary official docs and record source URLs for material claims.",
+        },
+        {
+            id: "agent-memory",
+            name: "Agent Memory",
+            description: "Prompt registry, handoffs, evidence, decisions, events, and lessons learned.",
+            priority: 8,
+            locations: [
+                ".generated-prompts/",
+                ".agent-workflow/events.jsonl",
+                ".agent-workflow/agent-lessons.jsonl",
+                ".agent-workflow/handoffs/",
+            ],
+            useWhen: [
+                "before repeated operations",
+                "before handoff",
+                "before final summary",
+            ],
+            verification: "Load only relevant entries for the current task, skill, tool, or error signature.",
+        },
+    ];
+}
+//# sourceMappingURL=knowledge-base.js.map

package/dist/knowledge-base.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge-base.js","sourceRoot":"","sources":["../src/knowledge-base.ts"],"names":[],"mappings":"AAUA,MAAM,UAAU,2BAA2B;IACzC,OAAO;QACL;YACE,EAAE,EAAE,sBAAsB;YAC1B,IAAI,EAAE,sBAAsB;YAC5B,WAAW,EACT,qEAAqE;YACvE,QAAQ,EAAE,CAAC;YACX,SAAS,EAAE,CAAC,WAAW,EAAE,cAAc,EAAE,WAAW,EAAE,aAAa,CAAC;YACpE,OAAO,EAAE;gBACP,iBAAiB;gBACjB,uBAAuB;gBACvB,uBAAuB;aACxB;YACD,YAAY,EACV,gFAAgF;SACnF;QACD;YACE,EAAE,EAAE,iBAAiB;YACrB,IAAI,EAAE,iBAAiB;YACvB,WAAW,EACT,+DAA+D;YACjE,QAAQ,EAAE,CAAC;YACX,SAAS,EAAE;gBACT,0CAA0C;gBAC1C,4BAA4B;gBAC5B,eAAe;aAChB;YACD,OAAO,EAAE,CAAC,wBAAwB,EAAE,uBAAuB,EAAE,WAAW,CAAC;YACzE,YAAY,EACV,wEAAwE;SAC3E;QACD;YACE,EAAE,EAAE,cAAc;YAClB,IAAI,EAAE,yBAAyB;YAC/B,WAAW,EACT,mFAAmF;YACrF,QAAQ,EAAE,CAAC;YACX,SAAS,EAAE;gBACT,WAAW;gBACX,4BAA4B;gBAC5B,gCAAgC;aACjC;YACD,OAAO,EAAE,CAAC,2BAA2B,EAAE,6BAA6B,CAAC;YACrE,YAAY,EAAE,yDAAyD;SACxE;QACD;YACE,EAAE,EAAE,UAAU;YACd,IAAI,EAAE,UAAU;YAChB,WAAW,EACT,6EAA6E;YAC/E,QAAQ,EAAE,CAAC;YACX,SAAS,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,cAAc,EAAE,eAAe,CAAC;YAC7D,OAAO,EAAE,CAAC,qBAAqB,EAAE,kBAAkB,EAAE,cAAc,CAAC;YACpE,YAAY,EACV,2EAA2E;SAC9E;QACD;YACE,EAAE,EAAE,kBAAkB;YACtB,IAAI,EAAE,sBAAsB;YAC5B,WAAW,EACT,6DAA6D;YAC/D,QAAQ,EAAE,CAAC;YACX,SAAS,EAAE;gBACT,YAAY;gBACZ,2BAA2B;gBAC3B,OAAO;gBACP,qBAAqB;aACtB;YACD,OAAO,EAAE,CAAC,eAAe,EAAE,gBAAgB,EAAE,oBAAoB,CAAC;YAClE,YAAY,EACV,iFAAiF;SACpF;QACD;YACE,EAAE,EAAE,gBAAgB;YACpB,IAAI,EAAE,oBAAoB;YAC1B,WAAW,EACT,yEAAyE;YAC3E,QAAQ,EAAE,CAAC;YACX,SAAS,EAAE;gBACT,oBAAoB;gBACpB,QAAQ;gBACR,mBAAmB;gBACnB,mBAAmB;aACpB;YACD,OAAO,EAAE;gBACP,yBAAyB;gBACzB,eAAe;gBACf,0BAA0B;aAC3B;YACD,YAAY,EACV,wFAAwF;SAC3F;QACD;YACE,EAAE,EAAE,aAAa;YACjB,IAAI,EAAE,+BAA+B;YACrC,WAAW,EACT,0EAA0E;YAC5E,QAAQ,EAAE,CAAC;YACX,SAAS,EAAE,CAAC,8CAA8C,CAAC;YAC3D,OAAO,EAAE;gBACP,cAAc;gBACd,mBAAmB;gBACnB,oBAAoB;gBACpB,wBAAwB;aACzB;YACD,YAAY,EACV,uEAAuE;SAC1E;QACD;YACE,EAAE,EAAE,cAAc;YAClB,IAAI,EAAE,cAAc;YACpB,WAAW,EACT,8EAA8E;YAChF,QAAQ,EAAE,CAAC;YACX,SAAS,EAAE;gBACT,qBAAqB;gBACrB,8BAA8B;gBAC9B,qCAAqC;gBACrC,2BAA2B;aAC5B;YACD,OAAO,EAAE;gBACP,4BAA4B;gBAC5B,gBAAgB;gBAChB,sBAAsB;aACvB;YACD,YAAY,EACV,mFAAmF;SACtF;KACF,CAAC;AACJ,CAAC"}

package/dist/mcp-oauth-proxy.d.ts

@@ -0,0 +1,39 @@
+export type McpProxyMode = "stdio-proxy" | "direct-http" | "tool-native-oauth";
+export type McpSecretStorage = "keychain" | "libsecret" | "windows-credential" | "secure-file";
+export interface McpOAuthProxyConfig {
+    enabled: boolean;
+    mode: McpProxyMode;
+    serverUrl: string;
+    tokenStorage: McpSecretStorage;
+    tokenPath?: string;
+    refreshWindowSeconds: number;
+    approvedBy?: string;
+}
+export interface McpProxyEvaluation {
+    approved: boolean;
+    risks: string[];
+    recommendations: string[];
+    modes: {
+        mode: McpProxyMode;
+        summary: string;
+        tradeOff: string;
+    }[];
+}
+export interface McpTokenState {
+    accessToken: string;
+    refreshToken: string;
+    expiresAt: string;
+}
+export interface McpTokenRefreshResult {
+    refreshed: boolean;
+    reason: string;
+    token: McpTokenState;
+}
+export declare function evaluateMcpOAuthProxy(config: McpOAuthProxyConfig): McpProxyEvaluation;
+export declare function validateMcpOAuthProxyConfig(config: McpOAuthProxyConfig): string[];
+export declare function refreshMcpTokenIfNeeded({ token, now, refreshWindowSeconds, refresh, }: {
+    token: McpTokenState;
+    now?: Date;
+    refreshWindowSeconds: number;
+    refresh: (token: McpTokenState) => Promise<McpTokenState>;
+}): Promise<McpTokenRefreshResult>;