@oneharness/sdk 0.6.14 → 0.6.16

package/dist/generated/sync-options.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Options accepted by the language SDKs' `sync()`.
+ */
+export interface SyncOptions {
+    /**
+     * Report what would change and write nothing.
+     */
+    check?: boolean | undefined;
+    config?: string | undefined;
+    cwd?: string | undefined;
+    global?: boolean | undefined;
+    harnesses?: string[] | undefined;
+    noConfig?: boolean | undefined;
+}

package/dist/generated/sync-options.js

@@ -0,0 +1,2 @@
+/* Generated from oneharness-core. Do not edit. */
+export {};

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

@@ -0,0 +1,64 @@
+/**
+ * What applying a fragment did (or, under `check`, would do) to one file.
+ *
+ * Serialized as the report token itself, so the wire value and the variant a
+ * consumer matches on cannot drift apart.
+ */
+export type FileStatus = "created" | "updated" | "unchanged";
+/**
+ * What one harness's permission/settings sync did (or would do).
+ *
+ * [`FileStatus`] plus the one outcome a *file* never has: a harness with no
+ * permission/settings fragment to apply at all. Keeping them one closed set —
+ * rather than the report's earlier free string — is what makes an unreachable
+ * status unconstructible and lets the contract publish the four values.
+ */
+export type SyncStatus = "created" | "updated" | "unchanged" | "skipped";
+/**
+ * The `oneharness sync` output contract.
+ */
+export interface SyncReport {
+    /**
+     * True under `--check`: statuses describe what *would* happen.
+     */
+    check: boolean;
+    /**
+     * The oneharness config files the synced settings came from.
+     */
+    config_files: string[];
+    results: SyncResult[];
+    schema_version: string;
+    [k: string]: unknown;
+}
+/**
+ * What one harness's sync did (or would do).
+ */
+export interface SyncResult {
+    /**
+     * The permission/settings config file written (or that would be written);
+     * `null` when nothing of that kind is configured for this harness.
+     */
+    file: string | null;
+    harness: string;
+    /**
+     * Normalized `[[hooks]]` files installed into this harness (a Goose hook
+     * writes two). Empty when no `[[hooks]]` entry targets it.
+     */
+    hooks: HookFileResult[];
+    status: SyncStatus;
+    /**
+     * Top-level settings that have no mapping for this harness (e.g. a
+     * top-level `allowed_tools` while the harness has no allow-list concept)
+     * — visible here and warned on stderr, never silently dropped.
+     */
+    unmapped: string[];
+    [k: string]: unknown;
+}
+/**
+ * One installed `[[hooks]]` file.
+ */
+export interface HookFileResult {
+    file: string;
+    status: FileStatus;
+    [k: string]: unknown;
+}

package/dist/generated/sync-report.js

@@ -0,0 +1,2 @@
+/* Generated from oneharness-core. Do not edit. */
+export {};

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

@@ -0,0 +1,15 @@
+/**
+ * Options accepted by the language SDKs' `usage()`.
+ */
+export interface UsageOptions {
+    all?: boolean | undefined;
+    bins?: {
+        [k: string]: string;
+    } | undefined;
+    config?: string | undefined;
+    cwd?: string | undefined;
+    exclude?: string[] | undefined;
+    harnesses?: string[] | undefined;
+    noConfig?: boolean | undefined;
+    timeoutSeconds?: number | undefined;
+}

package/dist/generated/usage-options.js

@@ -0,0 +1,2 @@
+/* Generated from oneharness-core. Do not edit. */
+export {};

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

@@ -0,0 +1,241 @@
+/**
+ * How the identity authenticates, which is what decides whether plan headroom
+ * exists at all.
+ */
+export type AuthMode = "subscription" | "api_key" | "unknown";
+/**
+ * Tri-state headroom availability.
+ *
+ * The three states are genuinely different answers and are never collapsed:
+ * `available` carries real data, `unavailable` is an affirmative "this identity
+ * has no plan headroom to report" **with a reason**, and `unknown` means only
+ * that nothing was learned. There is no percentage reachable from either
+ * non-available state, so neither can be rendered as `0%` used.
+ */
+export type UsageAvailability = {
+    state: "available";
+    windows: Windows;
+    [k: string]: unknown;
+} | {
+    reason: UnavailableReason;
+    state: "unavailable";
+    [k: string]: unknown;
+} | {
+    reason: UnknownReason;
+    state: "unknown";
+    [k: string]: unknown;
+};
+/**
+ * One rate-limit window. Emitted only for a window the harness actually
+ * reported: a null window (Claude's `seven_day_opus: null`, codex's `secondary:
+ * null`) means "not applicable to this plan", **not** "0% used", so it is
+ * omitted rather than zero-filled.
+ */
+export type UsageWindow = {
+    /**
+     * The harness-native window identifier, verbatim where the harness names
+     * one (`five_hour`, `tangelo`, `chat`) and `<limitId>/<slot>` where codex's
+     * two-level buckets are flattened.
+     */
+    id: string;
+    /**
+     * Whether this is the limit currently binding, when the harness says so
+     * (Claude's `limits[].is_active`). Absent when it does not.
+     */
+    is_binding?: boolean | null | undefined;
+    /**
+     * A human label the harness supplied (codex's `limitName`), when it did.
+     */
+    label?: string | null | undefined;
+    /**
+     * When the window resets, always absolute RFC 3339 UTC — a [`UtcInstant`],
+     * so no other text is representable here. Absent when the harness reported
+     * no reset, or one that could not be normalized.
+     */
+    resets_at?: UtcInstant | null | undefined;
+    /**
+     * The model display name this window is scoped to, when it is scoped.
+     */
+    scope?: string | null | undefined;
+    usage: WindowUsage;
+    [k: string]: unknown;
+} & UsageWindow1;
+/**
+ * An RFC 3339 timestamp in UTC (`Z`), in oneharness's canonical spelling.
+ */
+export type UtcInstant = string;
+/**
+ * What a window's consumption looks like. An unlimited quota carries no
+ * counters, so it can never be rendered as a metered bar at 0% used.
+ */
+export type WindowUsage = {
+    /**
+     * The raw counters behind the percentage, when the harness reported
+     * every one of them. Never partially fabricated, and absent rather than
+     * null when the payload did not carry the full set.
+     */
+    counters?: QuotaCounters | null | undefined;
+    kind: "metered";
+    /**
+     * **Always percent-used**, whatever polarity the source used, and
+     * validated at the boundary — see [`UsedPercent`].
+     */
+    used_percent: number;
+    [k: string]: unknown;
+} | {
+    kind: "unlimited";
+    [k: string]: unknown;
+};
+/**
+ * A counter that cannot legitimately be negative. An entitlement is a ceiling
+ * and a consumption is an amount spent; neither has a meaning below zero, so a
+ * negative one is a payload that failed to parse rather than an account state,
+ * and it is rejected at the boundary like [`UsedPercent`].
+ *
+ * Deliberately *not* used for [`QuotaCounters::remaining`], which is genuinely
+ * negative for an account past its ceiling — the deficit is the signal there,
+ * so constraining it would discard a real over-consumption reading.
+ */
+export type QuotaAmount = number;
+/**
+ * What the counters count.
+ */
+export type QuotaUnit = "ai_credits" | "unspecified";
+export type UsageWindow1 = {
+    window_seconds: number;
+    window_seconds_source: "reported";
+    [k: string]: unknown;
+} | {
+    window_seconds: number;
+    window_seconds_source: "inferred_from_id";
+    [k: string]: unknown;
+} | {
+    window_seconds_source: "unknown";
+    [k: string]: unknown;
+};
+/**
+ * A non-empty list of windows. The non-emptiness is the invariant that keeps
+ * "available" from ever meaning "no data" — construct it with [`Windows::new`].
+ */
+export type Windows = UsageWindow[];
+/**
+ * Why an identity affirmatively has no plan headroom. Distinct from
+ * [`UnknownReason`]: these are answers, not absences of one.
+ */
+export type UnavailableReason = "api_key_auth" | "not_logged_in" | "no_windows_reported" | "no_plan_quota" | "no_headroom_reader";
+/**
+ * Why nothing is known. Reserved **strictly** for unprobed or probe-failed —
+ * API-key auth is [`UnavailableReason::ApiKeyAuth`], not this.
+ */
+export type UnknownReason = {
+    kind: "unprobed";
+    [k: string]: unknown;
+} | {
+    kind: "probe_failed";
+    message: string;
+    [k: string]: unknown;
+} | {
+    bin: string;
+    kind: "binary_missing";
+    [k: string]: unknown;
+};
+/**
+ * One usage report: every probed identity, stamped with a single observation
+ * time supplied by the caller (this module reads no clock).
+ *
+ * Deserializing is a consumer boundary — `oneharness-core` is published for
+ * sibling tools — so the envelope is validated on the way in rather than
+ * trusted: see [`UsageReportWire`].
+ */
+export interface UsageReport {
+    identities: UsageIdentity[];
+    /**
+     * An RFC 3339 timestamp in UTC (`Z`), in oneharness's canonical spelling.
+     */
+    observed_at: string;
+    /**
+     * The shape version, as a type with one value — see [`SchemaVersion`].
+     */
+    schema_version: "0.1";
+    [k: string]: unknown;
+}
+/**
+ * One harness identity's headroom.
+ *
+ * Deserializing is a consumer boundary like the envelope's, so every string an
+ * identity carries is flattened through [`without_control_chars`] on the way in
+ * — see [`UsageIdentityWire`].
+ */
+export interface UsageIdentity {
+    auth_mode: AuthMode;
+    availability: UsageAvailability;
+    /**
+     * Canonical harness id, matching a [`crate::domain::harness`] registry id.
+     */
+    harness: string;
+    /**
+     * The plan as the harness spells it, **verbatim**: Claude's `max` and
+     * codex's `pro` are different vocabularies and are never unified into one
+     * enum. Absent when the harness reports no plan (an API-key session).
+     */
+    plan?: string | null | undefined;
+    /**
+     * How this identity was selected — never the credential itself.
+     */
+    selector: {
+        env: string;
+        kind: "env_path";
+        path: string;
+        [k: string]: unknown;
+    } | {
+        env: string;
+        kind: "env_secret";
+        [k: string]: unknown;
+    } | {
+        kind: "ambient";
+        [k: string]: unknown;
+    };
+    /**
+     * The named variant this identity came from, when it was selected by a
+     * composed id (`claude-code:work`). Absent for a bare harness id, matching
+     * [`crate::domain::report::RunResult::variant`] — so a consumer joins a
+     * usage identity to the runs it describes on the same pair of fields.
+     *
+     * Two subscriptions of one harness therefore stay distinguishable even when
+     * their [`IdentitySelector`]s do not distinguish them (a variant that
+     * selects an identity by credential rather than by directory).
+     *
+     * A [`VariantName`], so the field cannot be *set* to a name no config could
+     * have declared — the same enforcement [`UsageReport::observed_at`] gets
+     * from [`UtcInstant`]. It serializes transparently, so the wire keeps the
+     * plain string [`crate::domain::report::RunResult::variant`] carries.
+     */
+    variant?: string | null | undefined;
+    [k: string]: unknown;
+}
+/**
+ * The raw counters behind a metered window.
+ */
+export interface QuotaCounters {
+    entitlement: QuotaAmount;
+    /**
+     * Whether any quota remains on this plan.
+     */
+    has_quota: boolean;
+    /**
+     * Whether spending past the entitlement is permitted. `has_quota: false`
+     * *and* `overage_permitted: false` together are the machine-readable
+     * "exhausted and blocked" signal — see [`QuotaCounters::blocked`].
+     */
+    overage_permitted: boolean;
+    /**
+     * The server's own remaining figure, taken as authoritative rather than
+     * recomputed from `entitlement - used`: Copilot's observed values disagree
+     * by about 1 and the server's figure wins. Signed, and the one counter here
+     * that is: an account past its ceiling reports a real deficit.
+     */
+    remaining: number;
+    unit: QuotaUnit;
+    used: QuotaAmount;
+    [k: string]: unknown;
+}

package/dist/generated/usage-report.js

@@ -0,0 +1,2 @@
+/* Generated from oneharness-core. Do not edit. */
+export {};

package/dist/generated/zod.d.ts

@@ -1,38 +1,77 @@
 import { z } from "zod";
-import type { ActionEvent, BatchReport, ControlEvent, ControlReason, ControlReport, ControlVerb, ExecutionTelemetry, FailureKind, FallThrough, FallbackReport, OutputFormat, RunReport, RunResult, SessionReport, Status, TimingSource, ToolCallStatus, Usage, UtcInstant } from "./contracts.js";
+import type { ConfigOptions } from "./config-options.js";
+import type { ConfigReport, Field, Field10, Field2, Field3, Field4, Field5, Field6, Field7, Field8, Field9, HarnessReport, HookEntry, VariantReport } from "./config-report.js";
+import type { ActionEvent, BatchReport, ControlEvent, ControlReason, ControlReport, ControlVerb, ExecutionTelemetry, FailureKind, FallThrough, FallbackReport, RunReport, RunResult, SessionReport, Status, TimingSource, ToolCallStatus, Usage, UtcInstant } from "./contracts.js";
+import type { DetectOptions } from "./detect-options.js";
 import type { DetectInfo, DetectReport } from "./detection.js";
+import type { GateOptions } from "./gate-options.js";
 import type { HistoryRecord } from "./history.js";
+import type { HistoryClearOptions } from "./history-clear-options.js";
+import type { HistoryClearDryRun, HistoryClearRemoved, HistoryClearReport } from "./history-clear-report.js";
 import type { HistoryLine } from "./history-line.js";
 import type { HistoryList, HistorySessionSummary } from "./history-list.js";
 import type { HistoryListOptions } from "./history-list-options.js";
 import type { HistoryLookup, HistoryLookupByLast, HistoryLookupBySession } from "./history-lookup.js";
+import type { HistoryMigrateOptions } from "./history-migrate-options.js";
+import type { HistoryMigrateReport, MigrationSummary } from "./history-migrate-report.js";
 import type { HistoryRecords } from "./history-records.js";
 import type { HistoryEventLine, HistoryStreamEnvelope } from "./history-stream-envelope.js";
 import type { HistoryWatchOptions } from "./history-watch-options.js";
-import type { HistoryLabels, PermissionMode, RunOptions } from "./options.js";
+import type { InitOptions } from "./init-options.js";
+import type { InterruptOptions } from "./interrupt-options.js";
+import type { InterruptResponse } from "./interrupt-response.js";
+import type { MockOptions } from "./mock-options.js";
+import type { HistoryLabels, OutputFormat, PermissionMode, RunMode, RunOptions } from "./options.js";
 import type { HarnessInfo, ListReport, ModeInfo, VariantInfo } from "./registry.js";
 import type { RunStreamEnvelope } from "./run-stream-envelope.js";
+import type { SyncOptions } from "./sync-options.js";
+import type { FileStatus, HookFileResult, SyncReport, SyncResult, SyncStatus } 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";
 export type AbsolutePath = ControlReport["socket"];
 export type BatchStrategy = BatchReport["strategy"];
 export type ControlShape = ControlReport["mechanism"];
+export type IdentitySelector = UsageIdentity["selector"];
 export type ModeHeadless = ModeInfo["headless"];
 export type SessionPhase = SessionReport["phase"];
+export type UsedPercent = number;
 export declare const AbsolutePathSchema: z.ZodType<AbsolutePath>;
 export declare const ActionEventSchema: z.ZodType<ActionEvent>;
+export declare const AuthModeSchema: z.ZodType<AuthMode>;
 export declare const BatchReportSchema: z.ZodType<BatchReport>;
 export declare const BatchStrategySchema: z.ZodType<BatchStrategy>;
+export declare const ConfigOptionsSchema: z.ZodType<ConfigOptions>;
+export declare const ConfigReportSchema: z.ZodType<ConfigReport>;
 export declare const ControlEventSchema: z.ZodType<ControlEvent>;
 export declare const ControlReasonSchema: z.ZodType<ControlReason>;
 export declare const ControlReportSchema: z.ZodType<ControlReport>;
 export declare const ControlShapeSchema: z.ZodType<ControlShape>;
 export declare const ControlVerbSchema: z.ZodType<ControlVerb>;
 export declare const DetectInfoSchema: z.ZodType<DetectInfo>;
+export declare const DetectOptionsSchema: z.ZodType<DetectOptions>;
 export declare const DetectReportSchema: z.ZodType<DetectReport>;
 export declare const ExecutionTelemetrySchema: z.ZodType<ExecutionTelemetry>;
 export declare const FailureKindSchema: z.ZodType<FailureKind>;
 export declare const FallThroughSchema: z.ZodType<FallThrough>;
 export declare const FallbackReportSchema: z.ZodType<FallbackReport>;
+export declare const FieldSchema: z.ZodType<Field>;
+export declare const Field10Schema: z.ZodType<Field10>;
+export declare const Field2Schema: z.ZodType<Field2>;
+export declare const Field3Schema: z.ZodType<Field3>;
+export declare const Field4Schema: z.ZodType<Field4>;
+export declare const Field5Schema: z.ZodType<Field5>;
+export declare const Field6Schema: z.ZodType<Field6>;
+export declare const Field7Schema: z.ZodType<Field7>;
+export declare const Field8Schema: z.ZodType<Field8>;
+export declare const Field9Schema: z.ZodType<Field9>;
+export declare const FileStatusSchema: z.ZodType<FileStatus>;
+export declare const GateOptionsSchema: z.ZodType<GateOptions>;
 export declare const HarnessInfoSchema: z.ZodType<HarnessInfo>;
+export declare const HarnessReportSchema: z.ZodType<HarnessReport>;
+export declare const HistoryClearDryRunSchema: z.ZodType<HistoryClearDryRun>;
+export declare const HistoryClearOptionsSchema: z.ZodType<HistoryClearOptions>;
+export declare const HistoryClearRemovedSchema: z.ZodType<HistoryClearRemoved>;
+export declare const HistoryClearReportSchema: z.ZodType<HistoryClearReport>;
 export declare const HistoryEventLineSchema: z.ZodType<HistoryEventLine>;
 export declare const HistoryLabelsSchema: z.ZodType<HistoryLabels>;
 export declare const HistoryLineSchema: z.ZodType<HistoryLine>;
@@ -41,16 +80,30 @@ export declare const HistoryListOptionsSchema: z.ZodType<HistoryListOptions>;
 export declare const HistoryLookupSchema: z.ZodType<HistoryLookup>;
 export declare const HistoryLookupByLastSchema: z.ZodType<HistoryLookupByLast>;
 export declare const HistoryLookupBySessionSchema: z.ZodType<HistoryLookupBySession>;
+export declare const HistoryMigrateOptionsSchema: z.ZodType<HistoryMigrateOptions>;
+export declare const HistoryMigrateReportSchema: z.ZodType<HistoryMigrateReport>;
 export declare const HistoryRecordSchema: z.ZodType<HistoryRecord>;
 export declare const HistoryRecordsSchema: z.ZodType<HistoryRecords>;
 export declare const HistorySessionSummarySchema: z.ZodType<HistorySessionSummary>;
 export declare const HistoryStreamEnvelopeSchema: z.ZodType<HistoryStreamEnvelope>;
 export declare const HistoryWatchOptionsSchema: z.ZodType<HistoryWatchOptions>;
+export declare const HookEntrySchema: z.ZodType<HookEntry>;
+export declare const HookFileResultSchema: z.ZodType<HookFileResult>;
+export declare const IdentitySelectorSchema: z.ZodType<IdentitySelector>;
+export declare const InitOptionsSchema: z.ZodType<InitOptions>;
+export declare const InterruptOptionsSchema: z.ZodType<InterruptOptions>;
+export declare const InterruptResponseSchema: z.ZodType<InterruptResponse>;
 export declare const ListReportSchema: z.ZodType<ListReport>;
+export declare const MigrationSummarySchema: z.ZodType<MigrationSummary>;
+export declare const MockOptionsSchema: z.ZodType<MockOptions>;
 export declare const ModeHeadlessSchema: z.ZodType<ModeHeadless>;
 export declare const ModeInfoSchema: z.ZodType<ModeInfo>;
 export declare const OutputFormatSchema: z.ZodType<OutputFormat>;
 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 RunModeSchema: z.ZodType<RunMode>;
 export declare const RunOptionsSchema: z.ZodType<RunOptions>;
 export declare const RunReportSchema: z.ZodType<RunReport>;
 export declare const RunResultSchema: z.ZodType<RunResult>;
@@ -58,8 +111,23 @@ export declare const RunStreamEnvelopeSchema: z.ZodType<RunStreamEnvelope>;
 export declare const SessionPhaseSchema: z.ZodType<SessionPhase>;
 export declare const SessionReportSchema: z.ZodType<SessionReport>;
 export declare const StatusSchema: z.ZodType<Status>;
+export declare const SyncOptionsSchema: z.ZodType<SyncOptions>;
+export declare const SyncReportSchema: z.ZodType<SyncReport>;
+export declare const SyncResultSchema: z.ZodType<SyncResult>;
+export declare const SyncStatusSchema: z.ZodType<SyncStatus>;
 export declare const TimingSourceSchema: z.ZodType<TimingSource>;
 export declare const ToolCallStatusSchema: z.ZodType<ToolCallStatus>;
+export declare const UnavailableReasonSchema: z.ZodType<UnavailableReason>;
+export declare const UnknownReasonSchema: z.ZodType<UnknownReason>;
 export declare const UsageSchema: z.ZodType<Usage>;
+export declare const UsageAvailabilitySchema: z.ZodType<UsageAvailability>;
+export declare const UsageIdentitySchema: z.ZodType<UsageIdentity>;
+export declare const UsageOptionsSchema: z.ZodType<UsageOptions>;
+export declare const UsageReportSchema: z.ZodType<UsageReport>;
+export declare const UsageWindowSchema: z.ZodType<UsageWindow>;
+export declare const UsedPercentSchema: z.ZodType<UsedPercent>;
 export declare const UtcInstantSchema: z.ZodType<UtcInstant>;
 export declare const VariantInfoSchema: z.ZodType<VariantInfo>;
+export declare const VariantReportSchema: z.ZodType<VariantReport>;
+export declare const WindowUsageSchema: z.ZodType<WindowUsage>;
+export declare const WindowsSchema: z.ZodType<Windows>;