@harness-control/protocol 0.3.0 → 0.4.1

package/dist/accounts.d.ts

@@ -0,0 +1,312 @@
+import { z } from "zod";
+export declare const accountIdentitySchema: z.ZodObject<{
+    key: z.ZodString;
+    provider: z.ZodString;
+    scope_source: z.ZodEnum<{
+        provider: "provider";
+        operator: "operator";
+        local: "local";
+    }>;
+    label: z.ZodString;
+}, z.core.$strict>;
+export type AccountIdentity = z.infer<typeof accountIdentitySchema>;
+export declare const accountLimitSchema: z.ZodObject<{
+    id: z.ZodString;
+    label: z.ZodString;
+    kind: z.ZodEnum<{
+        quota: "quota";
+        spend: "spend";
+    }>;
+    used_percent: z.ZodOptional<z.ZodNumber>;
+    resets_at: z.ZodOptional<z.ZodISODateTime>;
+    window_minutes: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+export type AccountLimit = z.infer<typeof accountLimitSchema>;
+export declare const accountUsageAvailableSchema: z.ZodObject<{
+    status: z.ZodLiteral<"available">;
+    observed_at: z.ZodISODateTime;
+    account: z.ZodObject<{
+        key: z.ZodString;
+        provider: z.ZodString;
+        scope_source: z.ZodEnum<{
+            provider: "provider";
+            operator: "operator";
+            local: "local";
+        }>;
+        label: z.ZodString;
+    }, z.core.$strict>;
+    source: z.ZodEnum<{
+        codex_app_server: "codex_app_server";
+        claude_sdk_experimental: "claude_sdk_experimental";
+    }>;
+    plan: z.ZodOptional<z.ZodString>;
+    limits: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        label: z.ZodString;
+        kind: z.ZodEnum<{
+            quota: "quota";
+            spend: "spend";
+        }>;
+        used_percent: z.ZodOptional<z.ZodNumber>;
+        resets_at: z.ZodOptional<z.ZodISODateTime>;
+        window_minutes: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type AccountUsageAvailable = z.infer<typeof accountUsageAvailableSchema>;
+export declare const accountUsageUnavailableSchema: z.ZodObject<{
+    status: z.ZodLiteral<"unavailable">;
+    observed_at: z.ZodISODateTime;
+    reason: z.ZodEnum<{
+        disabled: "disabled";
+        unsupported: "unsupported";
+        unauthenticated: "unauthenticated";
+        not_applicable: "not_applicable";
+        timeout: "timeout";
+        provider_error: "provider_error";
+        invalid_response: "invalid_response";
+    }>;
+    message: z.ZodString;
+}, z.core.$strict>;
+export declare const accountUsageObservationSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    status: z.ZodLiteral<"available">;
+    observed_at: z.ZodISODateTime;
+    account: z.ZodObject<{
+        key: z.ZodString;
+        provider: z.ZodString;
+        scope_source: z.ZodEnum<{
+            provider: "provider";
+            operator: "operator";
+            local: "local";
+        }>;
+        label: z.ZodString;
+    }, z.core.$strict>;
+    source: z.ZodEnum<{
+        codex_app_server: "codex_app_server";
+        claude_sdk_experimental: "claude_sdk_experimental";
+    }>;
+    plan: z.ZodOptional<z.ZodString>;
+    limits: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        label: z.ZodString;
+        kind: z.ZodEnum<{
+            quota: "quota";
+            spend: "spend";
+        }>;
+        used_percent: z.ZodOptional<z.ZodNumber>;
+        resets_at: z.ZodOptional<z.ZodISODateTime>;
+        window_minutes: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
+}, z.core.$strict>, z.ZodObject<{
+    status: z.ZodLiteral<"unavailable">;
+    observed_at: z.ZodISODateTime;
+    reason: z.ZodEnum<{
+        disabled: "disabled";
+        unsupported: "unsupported";
+        unauthenticated: "unauthenticated";
+        not_applicable: "not_applicable";
+        timeout: "timeout";
+        provider_error: "provider_error";
+        invalid_response: "invalid_response";
+    }>;
+    message: z.ZodString;
+}, z.core.$strict>], "status">;
+export type AccountUsageObservation = z.infer<typeof accountUsageObservationSchema>;
+export declare const hcpAccountsReadPayloadSchema: z.ZodObject<{
+    provider_instance_ids: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>;
+export type HcpAccountsReadPayload = z.infer<typeof hcpAccountsReadPayloadSchema>;
+export declare const accountProviderReadingSchema: z.ZodObject<{
+    provider_instance_id: z.ZodString;
+    observation: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        status: z.ZodLiteral<"available">;
+        observed_at: z.ZodISODateTime;
+        account: z.ZodObject<{
+            key: z.ZodString;
+            provider: z.ZodString;
+            scope_source: z.ZodEnum<{
+                provider: "provider";
+                operator: "operator";
+                local: "local";
+            }>;
+            label: z.ZodString;
+        }, z.core.$strict>;
+        source: z.ZodEnum<{
+            codex_app_server: "codex_app_server";
+            claude_sdk_experimental: "claude_sdk_experimental";
+        }>;
+        plan: z.ZodOptional<z.ZodString>;
+        limits: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            label: z.ZodString;
+            kind: z.ZodEnum<{
+                quota: "quota";
+                spend: "spend";
+            }>;
+            used_percent: z.ZodOptional<z.ZodNumber>;
+            resets_at: z.ZodOptional<z.ZodISODateTime>;
+            window_minutes: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>, z.ZodObject<{
+        status: z.ZodLiteral<"unavailable">;
+        observed_at: z.ZodISODateTime;
+        reason: z.ZodEnum<{
+            disabled: "disabled";
+            unsupported: "unsupported";
+            unauthenticated: "unauthenticated";
+            not_applicable: "not_applicable";
+            timeout: "timeout";
+            provider_error: "provider_error";
+            invalid_response: "invalid_response";
+        }>;
+        message: z.ZodString;
+    }, z.core.$strict>], "status">;
+}, z.core.$strict>;
+export type AccountProviderReading = z.infer<typeof accountProviderReadingSchema>;
+export declare const hcpAccountsSnapshotPayloadSchema: z.ZodObject<{
+    request_id: z.ZodString;
+    host_id: z.ZodString;
+    providers: z.ZodArray<z.ZodObject<{
+        provider_instance_id: z.ZodString;
+        observation: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            status: z.ZodLiteral<"available">;
+            observed_at: z.ZodISODateTime;
+            account: z.ZodObject<{
+                key: z.ZodString;
+                provider: z.ZodString;
+                scope_source: z.ZodEnum<{
+                    provider: "provider";
+                    operator: "operator";
+                    local: "local";
+                }>;
+                label: z.ZodString;
+            }, z.core.$strict>;
+            source: z.ZodEnum<{
+                codex_app_server: "codex_app_server";
+                claude_sdk_experimental: "claude_sdk_experimental";
+            }>;
+            plan: z.ZodOptional<z.ZodString>;
+            limits: z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                label: z.ZodString;
+                kind: z.ZodEnum<{
+                    quota: "quota";
+                    spend: "spend";
+                }>;
+                used_percent: z.ZodOptional<z.ZodNumber>;
+                resets_at: z.ZodOptional<z.ZodISODateTime>;
+                window_minutes: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$strict>>;
+        }, z.core.$strict>, z.ZodObject<{
+            status: z.ZodLiteral<"unavailable">;
+            observed_at: z.ZodISODateTime;
+            reason: z.ZodEnum<{
+                disabled: "disabled";
+                unsupported: "unsupported";
+                unauthenticated: "unauthenticated";
+                not_applicable: "not_applicable";
+                timeout: "timeout";
+                provider_error: "provider_error";
+                invalid_response: "invalid_response";
+            }>;
+            message: z.ZodString;
+        }, z.core.$strict>], "status">;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type HcpAccountsSnapshotPayload = z.infer<typeof hcpAccountsSnapshotPayloadSchema>;
+export declare const accountSourceStateSchema: z.ZodObject<{
+    host_id: z.ZodString;
+    provider_instance_id: z.ZodString;
+    latest: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        status: z.ZodLiteral<"available">;
+        observed_at: z.ZodISODateTime;
+        account: z.ZodObject<{
+            key: z.ZodString;
+            provider: z.ZodString;
+            scope_source: z.ZodEnum<{
+                provider: "provider";
+                operator: "operator";
+                local: "local";
+            }>;
+            label: z.ZodString;
+        }, z.core.$strict>;
+        source: z.ZodEnum<{
+            codex_app_server: "codex_app_server";
+            claude_sdk_experimental: "claude_sdk_experimental";
+        }>;
+        plan: z.ZodOptional<z.ZodString>;
+        limits: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            label: z.ZodString;
+            kind: z.ZodEnum<{
+                quota: "quota";
+                spend: "spend";
+            }>;
+            used_percent: z.ZodOptional<z.ZodNumber>;
+            resets_at: z.ZodOptional<z.ZodISODateTime>;
+            window_minutes: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>, z.ZodObject<{
+        status: z.ZodLiteral<"unavailable">;
+        observed_at: z.ZodISODateTime;
+        reason: z.ZodEnum<{
+            disabled: "disabled";
+            unsupported: "unsupported";
+            unauthenticated: "unauthenticated";
+            not_applicable: "not_applicable";
+            timeout: "timeout";
+            provider_error: "provider_error";
+            invalid_response: "invalid_response";
+        }>;
+        message: z.ZodString;
+    }, z.core.$strict>], "status">;
+    last_success: z.ZodOptional<z.ZodObject<{
+        status: z.ZodLiteral<"available">;
+        observed_at: z.ZodISODateTime;
+        account: z.ZodObject<{
+            key: z.ZodString;
+            provider: z.ZodString;
+            scope_source: z.ZodEnum<{
+                provider: "provider";
+                operator: "operator";
+                local: "local";
+            }>;
+            label: z.ZodString;
+        }, z.core.$strict>;
+        source: z.ZodEnum<{
+            codex_app_server: "codex_app_server";
+            claude_sdk_experimental: "claude_sdk_experimental";
+        }>;
+        plan: z.ZodOptional<z.ZodString>;
+        limits: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            label: z.ZodString;
+            kind: z.ZodEnum<{
+                quota: "quota";
+                spend: "spend";
+            }>;
+            used_percent: z.ZodOptional<z.ZodNumber>;
+            resets_at: z.ZodOptional<z.ZodISODateTime>;
+            window_minutes: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type AccountSourceState = z.infer<typeof accountSourceStateSchema>;
+export type AccountUsageView = {
+    account: AccountIdentity;
+    observation: AccountUsageAvailable;
+    freshness: "fresh" | "stale" | "unavailable";
+    sources: Array<{
+        host_id: string;
+        provider_instance_id: string;
+    }>;
+};
+/** Store this projection in application storage; quota snapshots are never added together. */
+export declare class HcpAccountUsageReducer {
+    #private;
+    constructor(state?: readonly AccountSourceState[]);
+    apply(input: HcpAccountsSnapshotPayload): void;
+    removeSource(hostId: string, providerInstanceId: string): void;
+    snapshot(): AccountSourceState[];
+    accounts(now: Date, maxAgeMs: number): AccountUsageView[];
+}
+//# sourceMappingURL=accounts.d.ts.map

package/dist/accounts.js

@@ -0,0 +1,132 @@
+import { z } from "zod";
+const id = z.string().min(1).max(256);
+const timestamp = z.iso.datetime({ offset: true });
+export const accountIdentitySchema = z.object({
+    key: id,
+    provider: id,
+    scope_source: z.enum(["provider", "operator", "local"]),
+    label: z.string().min(1).max(256),
+}).strict();
+export const accountLimitSchema = z.object({
+    id,
+    label: z.string().min(1).max(256),
+    kind: z.enum(["quota", "spend"]),
+    used_percent: z.number().finite().nonnegative().optional(),
+    resets_at: timestamp.optional(),
+    window_minutes: z.number().int().positive().optional(),
+}).strict();
+export const accountUsageAvailableSchema = z.object({
+    status: z.literal("available"),
+    observed_at: timestamp,
+    account: accountIdentitySchema,
+    source: z.enum(["codex_app_server", "claude_sdk_experimental"]),
+    plan: id.optional(),
+    limits: z.array(accountLimitSchema).max(64),
+}).strict().superRefine((value, context) => {
+    if (new Set(value.limits.map(limit => limit.id)).size !== value.limits.length) {
+        context.addIssue({ code: "custom", path: ["limits"], message: "Limit ids must be unique." });
+    }
+});
+export const accountUsageUnavailableSchema = z.object({
+    status: z.literal("unavailable"),
+    observed_at: timestamp,
+    reason: z.enum(["disabled", "unsupported", "unauthenticated", "not_applicable", "timeout", "provider_error", "invalid_response"]),
+    message: z.string().min(1).max(512),
+}).strict();
+export const accountUsageObservationSchema = z.discriminatedUnion("status", [
+    accountUsageAvailableSchema, accountUsageUnavailableSchema,
+]);
+export const hcpAccountsReadPayloadSchema = z.object({
+    provider_instance_ids: z.array(id).min(1).max(32).optional(),
+}).strict().superRefine((value, context) => {
+    if (value.provider_instance_ids && new Set(value.provider_instance_ids).size !== value.provider_instance_ids.length) {
+        context.addIssue({ code: "custom", path: ["provider_instance_ids"], message: "Provider ids must be unique." });
+    }
+});
+export const accountProviderReadingSchema = z.object({
+    provider_instance_id: id,
+    observation: accountUsageObservationSchema,
+}).strict();
+export const hcpAccountsSnapshotPayloadSchema = z.object({
+    request_id: id,
+    host_id: id,
+    providers: z.array(accountProviderReadingSchema).max(32),
+}).strict().superRefine((value, context) => {
+    if (new Set(value.providers.map(provider => provider.provider_instance_id)).size !== value.providers.length) {
+        context.addIssue({ code: "custom", path: ["providers"], message: "Provider ids must be unique." });
+    }
+});
+export const accountSourceStateSchema = z.object({
+    host_id: id,
+    provider_instance_id: id,
+    latest: accountUsageObservationSchema,
+    last_success: accountUsageAvailableSchema.optional(),
+}).strict().superRefine((state, context) => {
+    if (state.latest.status === "available" && JSON.stringify(state.latest) !== JSON.stringify(state.last_success)) {
+        context.addIssue({ code: "custom", message: "An available source must retain the same successful observation." });
+    }
+    if (state.last_success && Date.parse(state.last_success.observed_at) > Date.parse(state.latest.observed_at)) {
+        context.addIssue({ code: "custom", message: "Successful observation cannot be newer than the latest observation." });
+    }
+});
+/** Store this projection in application storage; quota snapshots are never added together. */
+export class HcpAccountUsageReducer {
+    #sources = new Map();
+    constructor(state = []) {
+        for (const input of state) {
+            const source = accountSourceStateSchema.parse(input);
+            const key = sourceKey(source.host_id, source.provider_instance_id);
+            if (this.#sources.has(key))
+                throw new Error("Duplicate account source.");
+            this.#sources.set(key, source);
+        }
+    }
+    apply(input) {
+        const snapshot = hcpAccountsSnapshotPayloadSchema.parse(input);
+        for (const reading of snapshot.providers) {
+            const key = sourceKey(snapshot.host_id, reading.provider_instance_id);
+            const existing = this.#sources.get(key);
+            if (existing && Date.parse(existing.latest.observed_at) >= Date.parse(reading.observation.observed_at))
+                continue;
+            const success = reading.observation.status === "available"
+                ? reading.observation : existing?.last_success;
+            this.#sources.set(key, {
+                host_id: snapshot.host_id, provider_instance_id: reading.provider_instance_id,
+                latest: structuredClone(reading.observation), ...(success ? { last_success: structuredClone(success) } : {}),
+            });
+        }
+    }
+    removeSource(hostId, providerInstanceId) {
+        this.#sources.delete(sourceKey(hostId, providerInstanceId));
+    }
+    snapshot() {
+        return structuredClone([...this.#sources.values()]);
+    }
+    accounts(now, maxAgeMs) {
+        if (!Number.isFinite(now.getTime()) || !Number.isFinite(maxAgeMs) || maxAgeMs <= 0)
+            throw new Error("Invalid freshness bounds.");
+        const grouped = new Map();
+        for (const source of this.#sources.values()) {
+            if (!source.last_success)
+                continue;
+            const key = source.last_success.account.key;
+            const sources = grouped.get(key) ?? [];
+            sources.push(source);
+            grouped.set(key, sources);
+        }
+        return [...grouped.values()].map(sources => {
+            const selected = sources.reduce((a, b) => Date.parse(a.last_success.observed_at) >= Date.parse(b.last_success.observed_at) ? a : b);
+            const observation = structuredClone(selected.last_success);
+            const age = now.getTime() - Date.parse(observation.observed_at);
+            const freshness = selected.latest.status !== "available" ? "unavailable" : age < 0 || age > maxAgeMs ? "stale" : "fresh";
+            return {
+                account: observation.account, observation, freshness,
+                sources: sources.map(source => ({ host_id: source.host_id, provider_instance_id: source.provider_instance_id })),
+            };
+        });
+    }
+}
+function sourceKey(hostId, providerId) {
+    return JSON.stringify([hostId, providerId]);
+}
+//# sourceMappingURL=accounts.js.map