@oneharness/sdk 0.21.2 → 0.22.0

package/dist/generated/schemas.json

@@ -17603,6 +17603,169 @@
                     }
                 ]
             },
+            "ResetCredit": {
+                "description": "One listed reset credit. `status` and `reset_type` are the harness's own\nwords, **verbatim** like [`UsageIdentity::plan`], so a value this release\nhas never seen is reported as itself rather than refused.",
+                "type": "object",
+                "properties": {
+                    "description": {
+                        "type": [
+                            "string",
+                            "null"
+                        ]
+                    },
+                    "expires_at": {
+                        "description": "When the credit expires. Absent when the harness said it does not.",
+                        "anyOf": [
+                            {
+                                "$ref": "#/$defs/UtcInstant"
+                            },
+                            {
+                                "type": "null"
+                            }
+                        ]
+                    },
+                    "granted_at": {
+                        "$ref": "#/$defs/UtcInstant"
+                    },
+                    "id": {
+                        "description": "The harness's opaque identifier for this credit.",
+                        "type": "string"
+                    },
+                    "reset_type": {
+                        "description": "What the credit resets, as the harness spells it (codex:\n`codexRateLimits`).",
+                        "type": "string"
+                    },
+                    "status": {
+                        "description": "The credit's status as the harness spells it (codex: `available`,\n`redeeming`, `redeemed`, `unknown`).",
+                        "type": "string"
+                    },
+                    "title": {
+                        "type": [
+                            "string",
+                            "null"
+                        ]
+                    }
+                },
+                "required": [
+                    "id",
+                    "status",
+                    "reset_type",
+                    "granted_at"
+                ]
+            },
+            "ResetCredits": {
+                "description": "The banked rate-limit **reset credits** an identity holds — capacity a window\nat 100% used does not show. Harness-neutral: codex fills it from its\n`rateLimitResetCredits` summary, and a harness with no reader says so.\n\nLike [`UsageAvailability`], `unknown` means only that nothing was learned and\nis never zero: \"no credits\" is exactly `reported` with an `available_count`\nof 0.",
+                "oneOf": [
+                    {
+                        "description": "The harness answered with a credits summary.",
+                        "type": "object",
+                        "properties": {
+                            "available_count": {
+                                "description": "The harness's own count, and the authoritative total — never derived\nfrom `credits`, which the harness may cap below it.",
+                                "type": "integer",
+                                "format": "uint64",
+                                "minimum": 0
+                            },
+                            "credits": {
+                                "description": "The credits the harness listed. Absent when it reported only the\ncount; present — possibly empty, possibly shorter than\n`available_count` — when it listed them.",
+                                "type": [
+                                    "array",
+                                    "null"
+                                ],
+                                "items": {
+                                    "$ref": "#/$defs/ResetCredit"
+                                }
+                            },
+                            "state": {
+                                "type": "string",
+                                "const": "reported"
+                            }
+                        },
+                        "required": [
+                            "state",
+                            "available_count"
+                        ]
+                    },
+                    {
+                        "description": "Nothing was learned about this identity's credits.",
+                        "type": "object",
+                        "properties": {
+                            "reason": {
+                                "$ref": "#/$defs/ResetCreditsUnknown"
+                            },
+                            "state": {
+                                "type": "string",
+                                "const": "unknown"
+                            }
+                        },
+                        "required": [
+                            "state",
+                            "reason"
+                        ]
+                    }
+                ]
+            },
+            "ResetCreditsUnknown": {
+                "description": "Why an identity's reset credits are unknown.",
+                "oneOf": [
+                    {
+                        "description": "This oneharness reads no reset credits for this harness.",
+                        "type": "object",
+                        "properties": {
+                            "kind": {
+                                "type": "string",
+                                "const": "no_reader"
+                            }
+                        },
+                        "required": [
+                            "kind"
+                        ]
+                    },
+                    {
+                        "description": "The probe produced no rate-limit answer to read credits from — the\nidentity's `availability` says why.",
+                        "type": "object",
+                        "properties": {
+                            "kind": {
+                                "type": "string",
+                                "const": "no_answer"
+                            }
+                        },
+                        "required": [
+                            "kind"
+                        ]
+                    },
+                    {
+                        "description": "The harness answered, but its answer carried no credits summary.",
+                        "type": "object",
+                        "properties": {
+                            "kind": {
+                                "type": "string",
+                                "const": "not_reported"
+                            }
+                        },
+                        "required": [
+                            "kind"
+                        ]
+                    },
+                    {
+                        "description": "A summary was present but structurally malformed.",
+                        "type": "object",
+                        "properties": {
+                            "kind": {
+                                "type": "string",
+                                "const": "unreadable"
+                            },
+                            "message": {
+                                "type": "string"
+                            }
+                        },
+                        "required": [
+                            "kind",
+                            "message"
+                        ]
+                    }
+                ]
+            },
             "UnavailableReason": {
                 "description": "Why an identity affirmatively has no plan headroom. Distinct from\n[`UnknownReason`]: these are answers, not absences of one.",
                 "oneOf": [
@@ -17762,6 +17925,10 @@
                             "null"
                         ]
                     },
+                    "reset_credits": {
+                        "description": "The banked reset credits this identity holds, always serialized so its\nabsence is never read as \"none\". A report written before the field\nexisted reads it as `unknown` / `no_reader`.",
+                        "$ref": "#/$defs/ResetCredits"
+                    },
                     "selector": {
                         "description": "How this identity was selected — never the credential itself.",
                         "$ref": "#/$defs/IdentitySelector"
@@ -17778,7 +17945,8 @@
                     "harness",
                     "selector",
                     "auth_mode",
-                    "availability"
+                    "availability",
+                    "reset_credits"
                 ]
             },
             "UsageWindow": {

package/dist/generated/usage-report.d.ts

@@ -139,6 +139,23 @@ export type UnknownReason = {
     kind: "binary_missing";
     [k: string]: unknown;
 };
+/**
+ * Why an identity's reset credits are unknown.
+ */
+export type ResetCreditsUnknown = {
+    kind: "no_reader";
+    [k: string]: unknown;
+} | {
+    kind: "no_answer";
+    [k: string]: unknown;
+} | {
+    kind: "not_reported";
+    [k: string]: unknown;
+} | {
+    kind: "unreadable";
+    message: string;
+    [k: string]: unknown;
+};
 /**
  * One usage report: every probed identity, stamped with a single observation
  * time supplied by the caller (this module reads no clock).
@@ -179,6 +196,30 @@ export interface UsageIdentity {
      * enum. Absent when the harness reports no plan (an API-key session).
      */
     plan?: string | null | undefined;
+    /**
+     * The banked reset credits this identity holds, always serialized so its
+     * absence is never read as "none". A report written before the field
+     * existed reads it as `unknown` / `no_reader`.
+     */
+    reset_credits: {
+        /**
+         * The harness's own count, and the authoritative total — never derived
+         * from `credits`, which the harness may cap below it.
+         */
+        available_count: number;
+        /**
+         * The credits the harness listed. Absent when it reported only the
+         * count; present — possibly empty, possibly shorter than
+         * `available_count` — when it listed them.
+         */
+        credits?: ResetCredit[] | null | undefined;
+        state: "reported";
+        [k: string]: unknown;
+    } | {
+        reason: ResetCreditsUnknown;
+        state: "unknown";
+        [k: string]: unknown;
+    };
     /**
      * How this identity was selected — never the credential itself.
      */
@@ -239,3 +280,32 @@ export interface QuotaCounters {
     used: QuotaAmount;
     [k: string]: unknown;
 }
+/**
+ * One listed reset credit. `status` and `reset_type` are the harness's own
+ * words, **verbatim** like [`UsageIdentity::plan`], so a value this release
+ * has never seen is reported as itself rather than refused.
+ */
+export interface ResetCredit {
+    description?: string | null | undefined;
+    /**
+     * When the credit expires. Absent when the harness said it does not.
+     */
+    expires_at?: UtcInstant | null | undefined;
+    granted_at: UtcInstant;
+    /**
+     * The harness's opaque identifier for this credit.
+     */
+    id: string;
+    /**
+     * What the credit resets, as the harness spells it (codex:
+     * `codexRateLimits`).
+     */
+    reset_type: string;
+    /**
+     * The credit's status as the harness spells it (codex: `available`,
+     * `redeeming`, `redeemed`, `unknown`).
+     */
+    status: string;
+    title?: string | null | undefined;
+    [k: string]: unknown;
+}

package/dist/generated/zod.d.ts

@@ -31,13 +31,14 @@ import type { RunStreamEnvelope } from "./run-stream-envelope.js";
 import type { SyncOptions } from "./sync-options.js";
 import type { FileStatus, HookFileResult, RuleChange, RuleList, SyncReport, SyncResult, SyncStatus, UnmappedRule } from "./sync-report.js";
 import type { UsageOptions } from "./usage-options.js";
-import type { AuthMode, QuotaAmount, QuotaCounters, QuotaUnit, UnavailableReason, UnknownReason, UsageAvailability, UsageIdentity, UsageReport, UsageWindow, WindowUsage, Windows } from "./usage-report.js";
+import type { AuthMode, QuotaAmount, QuotaCounters, QuotaUnit, ResetCredit, ResetCreditsUnknown, UnavailableReason, UnknownReason, UsageAvailability, UsageIdentity, UsageReport, UsageWindow, WindowUsage, Windows } from "./usage-report.js";
 export type AbsolutePath = ControlReport["socket"];
 export type BatchStrategy = BatchReport["strategy"];
 export type ControlShape = ControlReport["mechanism"];
 export type IdentitySelector = UsageIdentity["selector"];
 export type IncompleteRunType = IncompleteHistoryRun["type"];
 export type ModeHeadless = ModeInfo["headless"];
+export type ResetCredits = UsageIdentity["reset_credits"];
 export type SessionPhase = SessionReport["phase"];
 export type UsedPercent = number;
 export declare const AbsolutePathSchema: z.ZodType<AbsolutePath>;
@@ -118,6 +119,9 @@ export declare const PermissionModeSchema: z.ZodType<PermissionMode>;
 export declare const QuotaAmountSchema: z.ZodType<QuotaAmount>;
 export declare const QuotaCountersSchema: z.ZodType<QuotaCounters>;
 export declare const QuotaUnitSchema: z.ZodType<QuotaUnit>;
+export declare const ResetCreditSchema: z.ZodType<ResetCredit>;
+export declare const ResetCreditsSchema: z.ZodType<ResetCredits>;
+export declare const ResetCreditsUnknownSchema: z.ZodType<ResetCreditsUnknown>;
 export declare const RuleChangeSchema: z.ZodType<RuleChange>;
 export declare const RuleListSchema: z.ZodType<RuleList>;
 export declare const RunModeSchema: z.ZodType<RunMode>;

package/dist/generated/zod.js

@@ -2465,6 +2465,44 @@ export const QuotaCountersSchema = z.looseObject({
     used: z.lazy(() => QuotaAmountSchema).refine((value) => value !== undefined, { message: "Required" }),
 });
 export const QuotaUnitSchema = z.union([z.literal("ai_credits"), z.literal("unspecified")]);
+export const ResetCreditSchema = z.looseObject({
+    description: z.union([z.string(), z.null()]).optional(),
+    expires_at: z.union([z.lazy(() => UtcInstantSchema), z.null()]).optional(),
+    granted_at: z.lazy(() => UtcInstantSchema).refine((value) => value !== undefined, { message: "Required" }),
+    id: z.string().refine((value) => value !== undefined, { message: "Required" }),
+    reset_type: z.string().refine((value) => value !== undefined, { message: "Required" }),
+    status: z.string().refine((value) => value !== undefined, { message: "Required" }),
+    title: z.union([z.string(), z.null()]).optional(),
+});
+export const ResetCreditsSchema = z.union([
+    z.looseObject({
+        available_count: z
+            .int()
+            .gte(0)
+            .refine((value) => value !== undefined, { message: "Required" }),
+        credits: z.union([z.array(z.lazy(() => ResetCreditSchema)), z.null()]).optional(),
+        state: z.literal("reported").refine((value) => value !== undefined, { message: "Required" }),
+    }),
+    z.looseObject({
+        reason: z.lazy(() => ResetCreditsUnknownSchema).refine((value) => value !== undefined, { message: "Required" }),
+        state: z.literal("unknown").refine((value) => value !== undefined, { message: "Required" }),
+    }),
+]);
+export const ResetCreditsUnknownSchema = z.union([
+    z.looseObject({
+        kind: z.literal("no_reader").refine((value) => value !== undefined, { message: "Required" }),
+    }),
+    z.looseObject({
+        kind: z.literal("no_answer").refine((value) => value !== undefined, { message: "Required" }),
+    }),
+    z.looseObject({
+        kind: z.literal("not_reported").refine((value) => value !== undefined, { message: "Required" }),
+    }),
+    z.looseObject({
+        kind: z.literal("unreadable").refine((value) => value !== undefined, { message: "Required" }),
+        message: z.string().refine((value) => value !== undefined, { message: "Required" }),
+    }),
+]);
 export const RuleChangeSchema = z.looseObject({
     list: z.union([z.lazy(() => RuleListSchema), z.null()]).optional(),
     rule: z.string().refine((value) => value !== undefined, { message: "Required" }),
@@ -2730,6 +2768,7 @@ export const UsageIdentitySchema = z.looseObject({
     availability: z.lazy(() => UsageAvailabilitySchema).refine((value) => value !== undefined, { message: "Required" }),
     harness: z.string().refine((value) => value !== undefined, { message: "Required" }),
     plan: z.union([z.string(), z.null()]).optional(),
+    reset_credits: z.lazy(() => ResetCreditsSchema).refine((value) => value !== undefined, { message: "Required" }),
     selector: z.lazy(() => IdentitySelectorSchema).refine((value) => value !== undefined, { message: "Required" }),
     variant: z.union([z.string(), z.null()]).optional(),
 });

package/dist/index.js

@@ -315,6 +315,8 @@ function capabilityArguments(method, options) {
                 args.push(binding.flag, String(value));
                 break;
             case "repeated":
+                // Zod validated this option against the contract, which types every
+                // `repeated` binding as an array.
                 pushMany(args, binding.flag, value.map(String));
                 break;
             case "switch":
@@ -322,10 +324,14 @@ function capabilityArguments(method, options) {
                     args.push(binding.flag);
                 break;
             case "key-value":
+                // Zod validated this option against the contract, which types every
+                // `key-value` binding as an object.
                 for (const [key, item] of Object.entries(value))
                     args.push(binding.flag, `${key}=${String(item)}`);
                 break;
             case "trailing":
+                // Zod validated this option against the contract, which types every
+                // `trailing` binding as an array.
                 trailing.push(...value.map(String));
                 break;
             case "window":

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oneharness/sdk",
-  "version": "0.21.2",
+  "version": "0.22.0",
   "description": "Typed Node.js SDK for oneharness",
   "type": "module",
   "main": "dist/index.js",
@@ -19,7 +19,7 @@
     "node": ">=20"
   },
   "dependencies": {
-    "oneharness-cli": "0.21.2",
+    "oneharness-cli": "0.22.0",
     "zod": "^4.4.3"
   }
 }