@hualinge/relay-api-server-contracts 0.1.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OfficeClaw Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,58 @@
+# @openjiuwen/relay-api-server-contracts
+
+Plugin contracts for OfficeClaw extensions. Auth is the first extension point.
+
+## Install
+
+```bash
+pnpm add @openjiuwen/relay-api-server-contracts
+```
+
+## Auth Provider Contract
+
+```ts
+import type { AuthProvider } from '@openjiuwen/relay-api-server-contracts/auth';
+
+const myProvider: AuthProvider = {
+  id: 'my-provider',
+  displayName: 'My Provider',
+  presentation: {
+    mode: 'form',
+    fields: [
+      { name: 'username', label: 'Username', type: 'text', required: true },
+      { name: 'password', label: 'Password', type: 'password', required: true },
+    ],
+    submitLabel: 'Sign In',
+  },
+  async authenticate(input) {
+    // Your authentication logic
+    return {
+      success: true,
+      principal: {
+        userId: input.credentials.username as string,
+        displayName: 'User',
+        expiresAt: null,
+      },
+    };
+  },
+};
+
+export default myProvider;
+```
+
+## Runtime Wiring
+
+Install your auth provider package into the app, then point the auth runtime at it:
+
+```bash
+CAT_CAFE_AUTH_PROVIDER=my-provider
+CAT_CAFE_AUTH_PROVIDER_MODULES=@examples/my-auth-provider
+```
+
+The platform will:
+
+1. import the module listed in `CAT_CAFE_AUTH_PROVIDER_MODULES`
+2. collect exported auth providers
+3. activate the provider whose `id` matches `CAT_CAFE_AUTH_PROVIDER`
+
+See [Build an Auth Provider](../../docs/guides/build-auth-provider.md) for the full walkthrough.

package/dist/auth.d.ts

@@ -0,0 +1,152 @@
+/**
+ * Auth Plugin API — the contract that third-party auth providers implement.
+ *
+ * Java analogy:
+ *   - This file is the `interface AuthProvider` jar.
+ *   - Third-party packages implement this interface and export an object.
+ *   - The main project installs the package, sets `.env`, and the runtime loads it.
+ *
+ * Design constraints (F140):
+ *   - Provider ID is a runtime string, never an enum/union.
+ *   - Provider only converts credentials → identity. No session, no middleware, no business logic.
+ *   - postLoginInit is provider-declared, platform-triggered, failure does not roll back auth.
+ *   - providerState is opaque to the platform — only the provider interprets it.
+ */
+export type AuthPresentationMode = 'auto' | 'form' | 'redirect';
+export interface AuthFieldOption {
+    value: string;
+    label: string;
+}
+export interface AuthFieldSchema {
+    name: string;
+    label: string;
+    type: 'text' | 'password' | 'select';
+    required?: boolean;
+    placeholder?: string;
+    options?: AuthFieldOption[];
+}
+export interface AuthPresentation {
+    /** How the frontend should handle login for this provider. */
+    mode: AuthPresentationMode;
+    /** Form fields (only meaningful when mode is 'form'). */
+    fields: AuthFieldSchema[];
+    /** Label for the submit button. */
+    submitLabel?: string;
+    /** Human-readable description shown on the login page. */
+    description?: string;
+    /** Redirect URL (only meaningful when mode is 'redirect'). */
+    redirectUrl?: string;
+}
+/**
+ * What a provider returns after successful authentication.
+ * The platform takes this and issues an internal session.
+ */
+export interface ExternalPrincipal {
+    /** User identifier, unique within this provider's namespace. */
+    userId: string;
+    /** Display name for the user (shown in UI viewer/profile). */
+    displayName?: string;
+    /** When the provider's credential expires. null = never. */
+    expiresAt: Date | null;
+    /** Opaque provider-owned data. Stored in session, only the provider reads it. */
+    providerState?: unknown;
+}
+export interface AuthenticateInput {
+    /** Credentials submitted by the user (form fields, callback params, etc.). */
+    credentials: Record<string, unknown>;
+}
+export interface AuthenticateResult {
+    success: true;
+    principal: ExternalPrincipal;
+}
+export interface AuthenticateFailure {
+    success: false;
+    message: string;
+    /** If true, the frontend should show a promotion-code / invite-code field. */
+    needCode?: boolean;
+}
+export type AuthenticateOutcome = AuthenticateResult | AuthenticateFailure;
+/**
+ * Session info passed to provider hooks (refresh, logout, postLoginInit).
+ * The provider can read its own providerState from here.
+ */
+export interface AuthSessionInfo {
+    sessionId: string;
+    userId: string;
+    providerId: string;
+    providerState: unknown;
+    expiresAt: Date | null;
+}
+export interface ProtocolCredentialResult {
+    baseUrl: string;
+    apiKey: string;
+    defaultHeaders: Record<string, string>;
+}
+/**
+ * The contract that every auth provider must satisfy.
+ *
+ * Required: id, displayName, presentation, authenticate.
+ * Optional: bootstrap, handleCallback, refresh, logout, restoreSession, postLoginInit, getPublicConfig, resolveProtocolCredential.
+ */
+export interface AuthProvider {
+    /** Unique provider identifier (runtime string, never hardcoded in platform). */
+    readonly id: string;
+    /** Human-readable name shown in logs and admin UI. */
+    readonly displayName: string;
+    /** Tells the frontend how to render the login experience. */
+    readonly presentation: AuthPresentation;
+    /**
+     * Called once at startup. Use for provider-level initialization
+     * (e.g., validate config, warm up connections).
+     */
+    bootstrap?(): Promise<void>;
+    /**
+     * Core: convert credentials into an identity.
+     * Must NOT perform business side-effects (MaaS init, model refresh, etc.).
+     */
+    authenticate(input: AuthenticateInput): Promise<AuthenticateOutcome>;
+    /**
+     * Handle OAuth/redirect callback (for redirect-mode providers).
+     * Called when the user returns from the external auth page.
+     */
+    handleCallback?(params: Record<string, string>): Promise<AuthenticateOutcome>;
+    /**
+     * Try to restore a session after server restart.
+     * Return an ExternalPrincipal if the session can be recovered, or null.
+     */
+    restoreSession?(userId: string): Promise<ExternalPrincipal | null>;
+    /**
+     * Refresh provider credentials before they expire.
+     * Return updated principal, or null if refresh is not possible.
+     */
+    refresh?(session: AuthSessionInfo): Promise<ExternalPrincipal | null>;
+    /**
+     * Provider-side cleanup on logout (e.g., revoke external tokens).
+     */
+    logout?(session: AuthSessionInfo): Promise<void>;
+    /**
+     * Provider-declared post-login initialization.
+     * Platform triggers this AFTER session issuance.
+     * Failure here does NOT roll back the successful authentication.
+     *
+     * Use for: MaaS subscription, model refresh, quota allocation, etc.
+     */
+    postLoginInit?(session: AuthSessionInfo): Promise<void>;
+    /**
+     * Return provider-specific public config (shown to unauthenticated users).
+     * Example: whether a promotion code has been remembered.
+     */
+    getPublicConfig?(): Promise<Record<string, unknown>>;
+    /**
+     * Resolve LLM-call credentials for a named protocol.
+     * Only implemented by auth providers whose cloud sessions carry model-call
+     * credentials (e.g., huawei-cas provides huawei_maas credentials).
+     *
+     * Platform looks up the session and passes AuthSessionInfo to the provider;
+     * the provider reads its own providerState — same pattern as refresh/logout.
+     *
+     * @returns Credential bundle for LLM API calls, or null if not supported.
+     */
+    resolveProtocolCredential?(protocol: string, session: AuthSessionInfo): ProtocolCredentialResult | null;
+}
+//# sourceMappingURL=auth.d.ts.map

package/dist/auth.d.ts.map

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

package/dist/auth.js

@@ -0,0 +1,16 @@
+/**
+ * Auth Plugin API — the contract that third-party auth providers implement.
+ *
+ * Java analogy:
+ *   - This file is the `interface AuthProvider` jar.
+ *   - Third-party packages implement this interface and export an object.
+ *   - The main project installs the package, sets `.env`, and the runtime loads it.
+ *
+ * Design constraints (F140):
+ *   - Provider ID is a runtime string, never an enum/union.
+ *   - Provider only converts credentials → identity. No session, no middleware, no business logic.
+ *   - postLoginInit is provider-declared, platform-triggered, failure does not roll back auth.
+ *   - providerState is opaque to the platform — only the provider interprets it.
+ */
+export {};
+//# sourceMappingURL=auth.js.map

package/dist/auth.js.map

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

package/dist/catalog.d.ts

@@ -0,0 +1,21 @@
+import type { OfficeClawConfig, OfficeClawConfigEntry } from '@openjiuwen/relay-shared';
+import type { GatewayIdentity } from './identity.js';
+export interface CatalogMemberEntry {
+    agentId: string;
+    config: OfficeClawConfigEntry;
+    readonly extend?: Readonly<Record<string, unknown>>;
+}
+export interface CatalogSnapshot {
+    catalog: OfficeClawConfig;
+}
+export interface CatalogProvider {
+    readonly id: string;
+    readonly displayName?: string;
+    readCatalog(identity: GatewayIdentity): Promise<CatalogSnapshot>;
+    writeCatalog(identity: GatewayIdentity, catalog: OfficeClawConfig): Promise<void>;
+    getMember?(identity: GatewayIdentity, agentId: string): Promise<CatalogMemberEntry | null>;
+    listRoutableMembers?(identity: GatewayIdentity): Promise<CatalogMemberEntry[]>;
+    bootstrap?(): Promise<void>;
+    shutdown?(): Promise<void>;
+}
+//# sourceMappingURL=catalog.d.ts.map

package/dist/catalog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.d.ts","sourceRoot":"","sources":["../src/catalog.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AACxF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAErD,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,qBAAqB,CAAC;IAC9B,QAAQ,CAAC,MAAM,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACrD;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,gBAAgB,CAAC;CAC3B;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAE9B,WAAW,CAAC,QAAQ,EAAE,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;IACjE,YAAY,CAAC,QAAQ,EAAE,eAAe,EAAE,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClF,SAAS,CAAC,CAAC,QAAQ,EAAE,eAAe,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC,CAAC;IAC3F,mBAAmB,CAAC,CAAC,QAAQ,EAAE,eAAe,GAAG,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAAC;IAC/E,SAAS,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5B,QAAQ,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5B"}

package/dist/catalog.js

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

package/dist/catalog.js.map

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

package/dist/evidence.d.ts

@@ -0,0 +1,109 @@
+export type EvidenceKind = 'feature' | 'decision' | 'plan' | 'session' | 'lesson' | 'thread' | 'discussion' | 'research';
+export type EvidenceStatus = 'active' | 'done' | 'archived';
+export interface EvidenceItem {
+    anchor: string;
+    kind: EvidenceKind;
+    status: EvidenceStatus;
+    title: string;
+    summary?: string;
+    keywords?: string[];
+    sourcePath?: string;
+    sourceHash?: string;
+    supersededBy?: string;
+    materializedFrom?: string;
+    updatedAt: string;
+    drillDown?: {
+        tool: string;
+        params: Record<string, string>;
+        hint: string;
+    };
+}
+export interface Edge {
+    fromAnchor: string;
+    toAnchor: string;
+    relation: 'evolved_from' | 'blocked_by' | 'related' | 'supersedes' | 'invalidates';
+}
+export interface SearchOptions {
+    kind?: EvidenceKind;
+    status?: EvidenceStatus;
+    keywords?: string[];
+    limit?: number;
+    scope?: 'docs' | 'memory' | 'threads' | 'sessions' | 'all';
+    mode?: 'lexical' | 'semantic' | 'hybrid';
+    depth?: 'summary' | 'raw';
+}
+export interface RebuildResult {
+    docsIndexed: number;
+    docsSkipped: number;
+    durationMs: number;
+}
+export interface ConsistencyReport {
+    ok: boolean;
+    docCount: number;
+    ftsCount: number;
+    mismatches: string[];
+}
+export interface EvidenceStats {
+    backend: string;
+    healthy: boolean;
+    degraded?: boolean;
+    docsCount?: number;
+    edgesCount?: number;
+    lastRebuildAt?: string | null;
+    reason?: string;
+}
+export interface EvidenceStore {
+    search(query: string, options?: SearchOptions): Promise<EvidenceItem[]>;
+    upsert(items: EvidenceItem[]): Promise<void>;
+    deleteByAnchor(anchor: string): Promise<void>;
+    getByAnchor(anchor: string): Promise<EvidenceItem | null>;
+    health(): Promise<boolean>;
+    initialize(): Promise<void>;
+    stats?(): Promise<EvidenceStats>;
+}
+export interface EvidenceIndex {
+    rebuild(options?: {
+        force?: boolean;
+    }): Promise<RebuildResult>;
+    incrementalUpdate(changedPaths: string[]): Promise<void>;
+    checkConsistency(): Promise<ConsistencyReport>;
+}
+export interface EvidenceProviderInput {
+    sqlitePath?: string;
+    docsRoot?: string;
+    markersDir?: string;
+    transcriptDataDir?: string;
+    embed?: Record<string, unknown>;
+    threadListFn?: () => Promise<Array<{
+        id: string;
+        title: string | null;
+        participants: string[];
+        threadMemory: {
+            summary: string;
+        } | null;
+        lastActiveAt: number;
+        featureIds?: string[];
+    }>>;
+    messageListFn?: (threadId: string, limit?: number) => Promise<Array<{
+        id: string;
+        content: string;
+        agentId?: string;
+        threadId: string;
+        timestamp: number;
+    }>>;
+    excludeThreadIdsFn?: () => Promise<Set<string>>;
+}
+export interface EvidenceServices {
+    backend: string;
+    store: EvidenceStore;
+    index?: EvidenceIndex;
+    close?(): void | Promise<void>;
+}
+export interface EvidenceProvider {
+    readonly id: string;
+    readonly displayName?: string;
+    createEvidenceServices(input: EvidenceProviderInput): EvidenceServices | Promise<EvidenceServices>;
+    bootstrap?(): Promise<void>;
+    shutdown?(): Promise<void>;
+}
+//# sourceMappingURL=evidence.d.ts.map

package/dist/evidence.d.ts.map

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

package/dist/evidence.js

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

package/dist/evidence.js.map

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

package/dist/identity.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Gateway Identity — the minimal identity struct passed through the gateway pipeline.
+ * Currently contains only userId; extensible for multi-tenant scenarios.
+ */
+export interface GatewayIdentity {
+    userId: string;
+}
+//# sourceMappingURL=identity.d.ts.map

package/dist/identity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity.d.ts","sourceRoot":"","sources":["../src/identity.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC;CAChB"}

package/dist/identity.js

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

package/dist/identity.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @openjiuwen/relay-api-server-contracts — Unified plugin contracts for OfficeClaw extensions.
+ *
+ * Extension points:
+ *   - Auth:     import type { AuthProvider } from '@openjiuwen/relay-api-server-contracts/auth';
+ *   - Identity: import type { GatewayIdentity } from '@openjiuwen/relay-api-server-contracts/identity';
+ *   - Storage:  import type { OfficeClawStorageProvider } from '@openjiuwen/relay-api-server-contracts/storage';
+ */
+export type { AuthenticateFailure, AuthenticateInput, AuthenticateOutcome, AuthenticateResult, AuthFieldOption, AuthFieldSchema, AuthPresentation, AuthPresentationMode, AuthProvider, AuthSessionInfo, ExternalPrincipal, ProtocolCredentialResult, } from './auth.js';
+export type { MetricsProvider, MetricsProviderInput, MetricsReporterConfig } from './metrics.js';
+export type { RuntimeEnvStore } from './runtime-env.js';
+export type { GatewayIdentity } from './identity.js';
+export type { CatalogMemberEntry, CatalogProvider, CatalogSnapshot } from './catalog.js';
+export type { ConsistencyReport, Edge, EvidenceIndex, EvidenceItem, EvidenceKind, EvidenceProvider, EvidenceProviderInput, EvidenceServices, EvidenceStats, EvidenceStatus, EvidenceStore, RebuildResult, SearchOptions, } from './evidence.js';
+export type { DynamicTaskDef, DynamicTaskPort, EmissionPort, EmissionRecord, EmissionRow, GlobalControl, GlobalControlPort, PackTemplateDef, PackTemplatePort, RunLedgerPort, RunLedgerQuery, RunLedgerRecord, RunLedgerRow, RunOutcome, RunStats, SchedulerPersistence, SchedulerProvider, SchedulerProviderInput, TaskOverride, TriggerSpec, } from './scheduler.js';
+export type { TelemetryProvider } from './telemetry-provider.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,YAAY,EACV,mBAAmB,EACnB,iBAAiB,EACjB,mBAAmB,EACnB,kBAAkB,EAClB,eAAe,EACf,eAAe,EACf,gBAAgB,EAChB,oBAAoB,EACpB,YAAY,EACZ,eAAe,EACf,iBAAiB,EACjB,wBAAwB,GACzB,MAAM,WAAW,CAAC;AACnB,YAAY,EAAE,eAAe,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AACjG,YAAY,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACxD,YAAY,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACrD,YAAY,EAAE,kBAAkB,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AACzF,YAAY,EACV,iBAAiB,EACjB,IAAI,EACJ,aAAa,EACb,YAAY,EACZ,YAAY,EACZ,gBAAgB,EAChB,qBAAqB,EACrB,gBAAgB,EAChB,aAAa,EACb,cAAc,EACd,aAAa,EACb,aAAa,EACb,aAAa,GACd,MAAM,eAAe,CAAC;AACvB,YAAY,EACV,cAAc,EACd,eAAe,EACf,YAAY,EACZ,cAAc,EACd,WAAW,EACX,aAAa,EACb,iBAAiB,EACjB,eAAe,EACf,gBAAgB,EAChB,aAAa,EACb,cAAc,EACd,eAAe,EACf,YAAY,EACZ,UAAU,EACV,QAAQ,EACR,oBAAoB,EACpB,iBAAiB,EACjB,sBAAsB,EACtB,YAAY,EACZ,WAAW,GACZ,MAAM,gBAAgB,CAAC;AACxB,YAAY,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC"}

package/dist/index.js

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

package/dist/index.js.map

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

package/dist/metrics.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Metrics Provider Plugin API — contract for metrics reporter config resolution.
+ *
+ * The provider resolves cloud-platform credentials into a reporter config
+ * (endpoint + token + projectId). The platform core owns the reporter lifecycle
+ * (creation, concurrency guard, periodic flush, shutdown).
+ */
+export interface MetricsReporterConfig {
+    endpoint: string;
+    token: string;
+    projectId: string;
+}
+export interface MetricsProviderInput {
+    providerState: unknown;
+    baseUrl: string;
+    instanceId?: string;
+    log?: {
+        info(msg: string): void;
+        info(obj: unknown, msg: string): void;
+        warn(msg: string): void;
+        warn(obj: unknown, msg: string): void;
+        error(msg: string): void;
+        error(obj: unknown, msg: string): void;
+    };
+}
+export interface MetricsProvider {
+    readonly id: string;
+    readonly displayName?: string;
+    bootstrap?(): Promise<void>;
+    shutdown?(): Promise<void>;
+    resolveReporterConfig(input: MetricsProviderInput): Promise<MetricsReporterConfig | null>;
+}
+//# sourceMappingURL=metrics.d.ts.map

package/dist/metrics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.d.ts","sourceRoot":"","sources":["../src/metrics.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,WAAW,qBAAqB;IACpC,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,oBAAoB;IACnC,aAAa,EAAE,OAAO,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,GAAG,CAAC,EAAE;QACJ,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;QACxB,IAAI,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;QACtC,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;QACxB,IAAI,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;QACtC,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;QACzB,KAAK,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;KACxC,CAAC;CACH;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAE9B,SAAS,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5B,QAAQ,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAE3B,qBAAqB,CAAC,KAAK,EAAE,oBAAoB,GAAG,OAAO,CAAC,qBAAqB,GAAG,IAAI,CAAC,CAAC;CAC3F"}

package/dist/metrics.js

@@ -0,0 +1,9 @@
+/**
+ * Metrics Provider Plugin API — contract for metrics reporter config resolution.
+ *
+ * The provider resolves cloud-platform credentials into a reporter config
+ * (endpoint + token + projectId). The platform core owns the reporter lifecycle
+ * (creation, concurrency guard, periodic flush, shutdown).
+ */
+export {};
+//# sourceMappingURL=metrics.js.map

package/dist/metrics.js.map

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

package/dist/runtime-env.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Runtime env contract shared by local API and remote gateway hosts.
+ *
+ * The store is responsible for:
+ * - loading persisted env key/value pairs at startup
+ * - persisting explicit runtime updates
+ *
+ * It is NOT responsible for auth, auditing, reconcile, or hot reload.
+ */
+export interface RuntimeEnvStore {
+    load(): Promise<Record<string, string>>;
+    save(updates: Record<string, string | null>): Promise<void>;
+}
+//# sourceMappingURL=runtime-env.d.ts.map

package/dist/runtime-env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-env.d.ts","sourceRoot":"","sources":["../src/runtime-env.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACxC,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7D"}

package/dist/runtime-env.js

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

package/dist/runtime-env.js.map

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