@tokensize/agent-client 0.3.0-beta.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TokenSize
+
+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,5 @@
+# `@tokensize/agent-client`
+
+The canonical local TokenSize client. It discovers installed coding harnesses, keeps normalized capability and allowance caches in `~/.tokensize`, requests a privacy-safe route from `api.tokensize.dev`, executes the selected local harness under the requested permission ceiling, and submits content-free feedback.
+
+Credentials, prompts, repository contents, and model output remain local unless prompt sharing is explicitly enabled. The CLI, Codex MCP server, and OpenCode plugin use this package rather than implementing separate clients.

package/dist/index.d.ts

@@ -0,0 +1,392 @@
+import { HarnessId, AgentModel, Allowance, TaskRole, PermissionProfile, RoutingObjective, AgentRouteResponse, AgentRouteRequest, RunEvent } from '@tokensize/agent-router';
+import { ChildProcess } from 'node:child_process';
+
+interface HarnessDiscovery {
+    harness: HarnessId;
+    installed: boolean;
+    executable?: string;
+    version?: string;
+    authenticated: boolean;
+    models: AgentModel[];
+    warnings: string[];
+    probeTimedOut?: boolean;
+}
+interface DiscoveryCacheMetadata {
+    hit: boolean;
+    refreshed?: boolean;
+    persisted?: boolean;
+    reason?: string;
+    path?: string;
+    createdAt?: string;
+    expiresAt?: string;
+    ageMs?: number;
+    warning?: string;
+}
+interface DiscoveryResult {
+    harnesses: HarnessDiscovery[];
+    cache: DiscoveryCacheMetadata;
+}
+interface DiscoveryOptions {
+    forceRefresh?: boolean;
+    reason?: string;
+}
+declare function opencodeModelIds(output: string): string[];
+declare function isCredentialFreeOpenCodeModel(id: string): boolean;
+declare const HARNESS_IDS: readonly HarnessId[];
+/** Probe one harness without invoking it for task execution. */
+declare function discoverHarness(harness: HarnessId): Promise<HarnessDiscovery>;
+declare function discoverHarnesses(): Promise<HarnessDiscovery[]>;
+declare function discoverHarnessesCached(options?: DiscoveryOptions): Promise<DiscoveryResult>;
+declare function flattenModels(discovery: HarnessDiscovery[], maximum?: number): AgentModel[];
+
+interface RunResult {
+    code: number | null;
+    stdout: string;
+    stderr: string;
+    timedOut: boolean;
+}
+/** Signal only the process group created for a TokenSize child command. */
+declare function terminateProcessTree(child: ChildProcess, signal: NodeJS.Signals): void;
+declare function run(command: string, args: string[], options?: {
+    cwd?: string;
+    input?: string;
+    timeoutMs?: number;
+    maxBytes?: number;
+    env?: NodeJS.ProcessEnv;
+}): Promise<RunResult>;
+
+declare function home(): string;
+declare function saveApiKey(apiKey: string): Promise<void>;
+declare function readApiKey(): Promise<string | null>;
+declare function installationId(): Promise<string>;
+interface LastRouteReceipt {
+    routeId: string;
+    runId?: string;
+    feedbackToken: string;
+    expiresAt: string;
+    targetId: string | null;
+}
+/**
+ * The local policy document: one owner-only file both hands edit — the human
+ * through `tokensize policy` or the web UI defaults, agents by reading it.
+ * Local values are ceilings; a hosted policy can only narrow them (see
+ * `mergePolicy` in @tokensize/agent-router). Environment variables still
+ * override for CI, but the file is the durable source.
+ */
+interface LocalPolicy {
+    rootHarness?: string;
+    rootQualityPrior?: number;
+    objective?: "quality" | "balanced" | "tokens" | "latency";
+    permissionCeiling?: "inspect" | "edit" | "test" | "network";
+    maxDelegationDepth?: number;
+    subscriptionHarnesses?: string[];
+    sharePromptDefault?: boolean;
+}
+declare function readLocalPolicy(): Promise<LocalPolicy>;
+declare function saveLocalPolicy(patch: Partial<LocalPolicy>): Promise<LocalPolicy>;
+declare function saveLastRoute(receipt: LastRouteReceipt): Promise<void>;
+declare function readLastRoute(): Promise<LastRouteReceipt>;
+
+interface HarnessAllowance {
+    default: Allowance;
+    byModelId?: Record<string, Allowance>;
+}
+interface AllowanceSnapshot {
+    harnesses: Partial<Record<HarnessId, HarnessAllowance>>;
+    cache: {
+        hit: boolean;
+        path: string;
+        createdAt: string;
+        expiresAt: string;
+    };
+}
+declare function parseClaudeUsage(raw: string): HarnessAllowance;
+declare function allowances(discovery: HarnessDiscovery[], forceRefresh?: boolean): Promise<AllowanceSnapshot>;
+declare function applyAllowances(discovery: HarnessDiscovery[], snapshot: AllowanceSnapshot): HarnessDiscovery[];
+declare function rootAllowance(harness: HarnessId, snapshot: AllowanceSnapshot): Allowance;
+declare function allowanceScopesForHarness(item: HarnessDiscovery): ({
+    modelCount: number;
+    allowance: {
+        status: "unknown" | "available" | "low" | "exhausted" | "unmetered";
+        observedAt: string;
+        source: "runtime-reported" | "unavailable" | "credential-free";
+        remainingFraction?: number | undefined;
+        resetsAt?: string | undefined;
+    } & {
+        remainingPercent?: number;
+    };
+    sampleModelIds: string[];
+    omittedModelCount: number;
+} | {
+    modelCount: number;
+    allowance: {
+        status: "unknown" | "available" | "low" | "exhausted" | "unmetered";
+        observedAt: string;
+        source: "runtime-reported" | "unavailable" | "credential-free";
+        remainingFraction?: number | undefined;
+        resetsAt?: string | undefined;
+    } & {
+        remainingPercent?: number;
+    };
+    modelIds: string[];
+})[];
+/** A labeled, display-safe view that distinguishes harness defaults from model-scoped limits. */
+declare function allowanceReport(discovery: HarnessDiscovery[], snapshot: AllowanceSnapshot): {
+    harness: "codex" | "claude" | "copilot" | "cursor" | "opencode" | "custom";
+    harnessDefault: {
+        status: "unknown" | "available" | "low" | "exhausted" | "unmetered";
+        observedAt: string;
+        source: "runtime-reported" | "unavailable" | "credential-free";
+        remainingFraction?: number | undefined;
+        resetsAt?: string | undefined;
+    } & {
+        remainingPercent?: number;
+    };
+    modelScopes: ({
+        modelCount: number;
+        allowance: {
+            status: "unknown" | "available" | "low" | "exhausted" | "unmetered";
+            observedAt: string;
+            source: "runtime-reported" | "unavailable" | "credential-free";
+            remainingFraction?: number | undefined;
+            resetsAt?: string | undefined;
+        } & {
+            remainingPercent?: number;
+        };
+        sampleModelIds: string[];
+        omittedModelCount: number;
+    } | {
+        modelCount: number;
+        allowance: {
+            status: "unknown" | "available" | "low" | "exhausted" | "unmetered";
+            observedAt: string;
+            source: "runtime-reported" | "unavailable" | "credential-free";
+            remainingFraction?: number | undefined;
+            resetsAt?: string | undefined;
+        } & {
+            remainingPercent?: number;
+        };
+        modelIds: string[];
+    })[];
+}[];
+
+declare function executionArgs(harness: HarnessId, model: string, permission: "inspect" | "edit" | "test" | "network", cwd: string): string[];
+
+interface TokenSizeClientOptions {
+    apiUrl?: string;
+    clientSurface?: AgentRouteRequest["client"]["surface"];
+    clientVersion?: string;
+    rootHarness?: HarnessId;
+    rootActive?: boolean;
+    rootQualityPrior?: number;
+    maxDelegationDepth?: number;
+    fetchImpl?: typeof fetch;
+    openBrowser?: (url: string) => void;
+}
+interface RouteOptions {
+    task: string;
+    role?: TaskRole;
+    permission?: PermissionProfile;
+    objective?: RoutingObjective;
+    sharePrompt?: boolean;
+    refresh?: boolean;
+    timeoutMs?: number;
+}
+interface RoutePreview {
+    receiptId: string;
+    /** Present when the service created a Run document for this route. */
+    runId?: string;
+    route: Omit<AgentRouteResponse, "feedbackToken">;
+    cache: {
+        discovery: DiscoveryCacheMetadata;
+        allowance: Awaited<ReturnType<typeof allowances>>["cache"];
+    };
+    harnesses: Array<ReturnType<typeof summarizeHarness>>;
+}
+/** Shape of a Run document as served by GET /v1/runs/:id. */
+interface RunDocumentView {
+    runId: string;
+    status: string;
+    events: Array<{
+        seq: number;
+        at: string;
+        actor: string;
+        type: string;
+        data: Record<string, unknown>;
+    }>;
+    decision: {
+        plan: {
+            targetId: string | null;
+            workflow: string;
+        };
+        reasonCodes: string[];
+        confidence: number;
+    };
+    approvals: Array<{
+        kind: string;
+        state: string;
+        surface?: string;
+        at: string;
+    }>;
+    createdAt: string;
+    expiresAt: string;
+    [key: string]: unknown;
+}
+interface StatusResult {
+    service: {
+        url: string;
+        authenticated: boolean;
+        catalog?: unknown;
+    };
+    installationId: string;
+    cache: {
+        discovery: DiscoveryCacheMetadata;
+        allowance: Awaited<ReturnType<typeof allowances>>["cache"];
+    };
+    harnesses: Array<ReturnType<typeof summarizeHarness>>;
+}
+declare function summarizeHarness(item: HarnessDiscovery, verbose?: boolean): {
+    harness: "codex" | "claude" | "copilot" | "cursor" | "opencode" | "custom";
+    installed: boolean;
+    authenticated: boolean;
+    version: string | undefined;
+    modelCount: number;
+    allowanceScopes: ({
+        modelCount: number;
+        allowance: {
+            status: "unknown" | "available" | "low" | "exhausted" | "unmetered";
+            observedAt: string;
+            source: "runtime-reported" | "unavailable" | "credential-free";
+            remainingFraction?: number | undefined;
+            resetsAt?: string | undefined;
+        } & {
+            remainingPercent?: number;
+        };
+        sampleModelIds: string[];
+        omittedModelCount: number;
+    } | {
+        modelCount: number;
+        allowance: {
+            status: "unknown" | "available" | "low" | "exhausted" | "unmetered";
+            observedAt: string;
+            source: "runtime-reported" | "unavailable" | "credential-free";
+            remainingFraction?: number | undefined;
+            resetsAt?: string | undefined;
+        } & {
+            remainingPercent?: number;
+        };
+        modelIds: string[];
+    })[];
+    warnings: string[];
+} | {
+    models: {
+        id: string;
+        harness: "codex" | "claude" | "copilot" | "cursor" | "opencode" | "custom";
+        nativeModelId: string;
+        displayName: string;
+        readiness: "installed" | "auth-ready" | "model-listed" | "invocation-compatible" | "live-confirmed";
+        authMode: "unknown" | "subscription" | "api-key" | "cloud-provider" | "local";
+        productUseApproved: boolean;
+        capabilities: {
+            tools: boolean;
+            vision: boolean;
+            structuredOutput: "none" | "json" | "jsonl" | "schema";
+            sessions: "none" | "resume" | "continue";
+            permissions: ("inspect" | "test" | "edit" | "network")[];
+        };
+        identityProof: "runtime-reported" | "unavailable" | "requested";
+        qualityPrior: number;
+        tokenEfficiencyPrior: number;
+        latencyPrior: number;
+        allowance: {
+            status: "unknown" | "available" | "low" | "exhausted" | "unmetered";
+            observedAt: string;
+            source: "runtime-reported" | "unavailable" | "credential-free";
+            remainingFraction?: number | undefined;
+            resetsAt?: string | undefined;
+        } | undefined;
+    }[];
+    harness: "codex" | "claude" | "copilot" | "cursor" | "opencode" | "custom";
+    installed: boolean;
+    authenticated: boolean;
+    version: string | undefined;
+    modelCount: number;
+    allowanceScopes: ({
+        modelCount: number;
+        allowance: {
+            status: "unknown" | "available" | "low" | "exhausted" | "unmetered";
+            observedAt: string;
+            source: "runtime-reported" | "unavailable" | "credential-free";
+            remainingFraction?: number | undefined;
+            resetsAt?: string | undefined;
+        } & {
+            remainingPercent?: number;
+        };
+        sampleModelIds: string[];
+        omittedModelCount: number;
+    } | {
+        modelCount: number;
+        allowance: {
+            status: "unknown" | "available" | "low" | "exhausted" | "unmetered";
+            observedAt: string;
+            source: "runtime-reported" | "unavailable" | "credential-free";
+            remainingFraction?: number | undefined;
+            resetsAt?: string | undefined;
+        } & {
+            remainingPercent?: number;
+        };
+        modelIds: string[];
+    })[];
+    warnings: string[];
+};
+declare class TokenSizeClient {
+    private readonly options;
+    constructor(options?: TokenSizeClientOptions);
+    /**
+     * Resolve routing defaults: explicit constructor options win, then
+     * environment variables (CI overrides), then the local policy document at
+     * ~/.tokensize/policy.json, then fail-closed defaults.
+     */
+    private resolvedDefaults;
+    private key;
+    private api;
+    status(options?: {
+        refresh?: boolean;
+        verbose?: boolean;
+    }): Promise<StatusResult>;
+    connect(surface?: "codex-plugin" | "opencode-plugin"): Promise<void>;
+    private prepare;
+    route(options: RouteOptions): Promise<RoutePreview>;
+    /** List recent Run documents for this tenant. */
+    runs(options?: {
+        limit?: number;
+    }): Promise<unknown>;
+    /** Read one Run document — the authoritative story of a delegation. */
+    runDocument(runId: string): Promise<RunDocumentView>;
+    /** Append one event to a Run. Execution-class events need the receipt token. */
+    appendRunEvent(runId: string, event: Omit<RunEvent, "seq"> & {
+        seq?: number;
+    }, options?: {
+        receiptToken?: string;
+    }): Promise<unknown>;
+    /** The human hand at the terminal: grant a pending approval on a Run. */
+    approve(runId: string, kind?: "subscription-use" | "execute" | "share-prompt"): Promise<unknown>;
+    /** Cancel a Run from any surface that can authenticate. */
+    cancel(runId: string): Promise<unknown>;
+    execute(options: {
+        receiptId: string;
+        task: string;
+        cwd?: string;
+    }): Promise<unknown>;
+    private recordRunEvent;
+    feedback(options: {
+        receiptId: string;
+        rating: 1 | 2 | 3 | 4 | 5;
+        modelChoice: "right" | "acceptable" | "wrong";
+        wouldUseAgain: boolean;
+        task?: string;
+    }): Promise<unknown>;
+}
+declare function createTokenSizeClient(options?: TokenSizeClientOptions): TokenSizeClient;
+
+export { type AllowanceSnapshot, type DiscoveryCacheMetadata, type DiscoveryOptions, type DiscoveryResult, HARNESS_IDS, type HarnessAllowance, type HarnessDiscovery, type LastRouteReceipt, type LocalPolicy, type RouteOptions, type RoutePreview, type RunDocumentView, type RunResult, type StatusResult, TokenSizeClient, type TokenSizeClientOptions, allowanceReport, allowanceScopesForHarness, allowances, applyAllowances, createTokenSizeClient, discoverHarness, discoverHarnesses, discoverHarnessesCached, executionArgs, flattenModels, home, installationId, isCredentialFreeOpenCodeModel, opencodeModelIds, parseClaudeUsage, readApiKey, readLastRoute, readLocalPolicy, rootAllowance, run, saveApiKey, saveLastRoute, saveLocalPolicy, terminateProcessTree };