@hasna/skills 0.3.0 → 0.4.0

package/dist/lib/auth-store.d.ts

@@ -87,7 +87,7 @@ export declare function getAuthConfigReadOnly(env?: Env, options?: SkillsFleetOp
  * Returns the file it wrote, so the CLI can name the real path rather than a
  * path it assumed.
  */
-export declare function saveAuthConfig(config: StoredAuthConfig, env?: Env): string;
+export declare function saveAuthConfig(config: StoredAuthConfig, env?: Env, authenticatedOrigin?: string): string;
 /** Store (or clear, with null) the API URL beside the credential. */
 export declare function saveApiUrl(apiUrl: string | null, env?: Env): string;
 /** The API URL recorded in the credentials file, or null. */

package/dist/lib/fleet-credentials.d.ts

@@ -114,7 +114,7 @@ export interface LocalSkillsFleet {
 }
 export type SkillsFleet = HostedSkillsFleet | LocalSkillsFleet;
 /** Machine-readable reasons a hosted resolution was refused. */
-export type SkillsFleetErrorCode = "MISSING_API_CREDENTIAL" | "INVALID_API_URL";
+export type SkillsFleetErrorCode = "MISSING_API_CREDENTIAL" | "INVALID_API_URL" | "INSTANCE_CREDENTIAL_MISMATCH";
 /**
  * A configured install could not produce a usable hosted client.
  *
@@ -151,7 +151,7 @@ export interface ConfiguredSkillsApiUrl {
  * default apply for a credentialled install and what keeps an install with no
  * credential from naming a host at all.
  */
-export declare function configuredSkillsApiUrl(env?: Env, keychain?: KeychainTierOptions): ConfiguredSkillsApiUrl | null;
+export declare function configuredSkillsApiUrl(env?: Env, keychain?: KeychainTierOptions, profile?: string): ConfiguredSkillsApiUrl | null;
 /** The credential file paths consulted, for a message that has to name them. */
 export declare function skillsCredentialFiles(env?: Env): string[];
 /**
@@ -193,6 +193,10 @@ export declare function resolveSkillsFleet(env?: Env, options?: SkillsFleetOptio
  * when a credential is configured and cannot be produced — never a fallback.
  */
 export declare function resolveSkillsApiKey(env?: Env, options?: SkillsFleetOptions): Promise<string | null>;
+/** Resolve the URL and credential once, including any asynchronous vault lookup. */
+export declare function resolveSkillsConnection(env?: Env, options?: SkillsFleetOptions): Promise<(HostedSkillsFleet & {
+    apiKey: string;
+}) | null>;
 /** The usable API key, or throw naming what is missing. Use on every send path. */
 export declare function requireSkillsApiKey(action?: string, env?: Env, options?: SkillsFleetOptions): Promise<string>;
 /**
@@ -206,9 +210,11 @@ export declare function requireSkillsApiKey(action?: string, env?: Env, options?
  */
 export declare function skillsCredentialOrReason(env?: Env, options?: SkillsFleetOptions): Promise<{
     apiKey: string;
+    apiOrigin: string;
     reason: null;
 } | {
     apiKey: null;
+    apiOrigin: null;
     reason: string | null;
 }>;
 /**

package/dist/lib/instance-credentials-race.fixture.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/lib/instance-credentials.d.ts

@@ -0,0 +1,13 @@
+export declare const SKILLS_BOUND_API_URL = "HASNA_SKILLS_BOUND_API_URL";
+type Env = Record<string, string | undefined>;
+/** Match the shared resolver's profile syntax before using its path helper. */
+export declare function selectedSkillsProfile(env: Env, explicit?: string): string | null;
+export declare function skillsProfileCredentialFiles(env: Env, explicit?: string): string[];
+/** Fence the released credential reader and this package's routing reads together. */
+export declare function captureSkillsCredentialFiles(files: string[]): () => void;
+/** Read only known non-secret routing fields, never export an API key or an arbitrary field. */
+export declare function readSkillsInstanceMetadata(file: string): {
+    apiUrl?: string;
+    binding?: string;
+};
+export {};

package/dist/lib/mcp-contracts.d.ts

@@ -9,6 +9,10 @@ export interface JsonSchemaObject {
     default?: unknown;
     format?: string;
     minimum?: number;
+    maximum?: number;
+    pattern?: string;
+    maxItems?: number;
+    maxLength?: number;
     items?: JsonSchemaObject;
     properties?: Record<string, JsonSchemaObject>;
     required?: string[];

package/dist/lib/portable-skills-files.d.ts

@@ -22,10 +22,14 @@ export declare function parseSkillKind(value: string | undefined): SkillKind | u
 export declare function readDeclaredSkillVersion(skillPath: string): string | undefined;
 export declare function createInstructionManifest(name: string, options: {
     description: string;
+    category?: string;
+    tags?: string[];
 }): PortableSkillManifest;
 export declare function writeInstructionSkillTemplate(skillPath: string, manifest: PortableSkillManifest): void;
 export declare function createPortableManifest(name: string, options: {
     description: string;
+    category?: string;
+    tags?: string[];
 }): PortableSkillManifest;
 export declare function writePortableSkillTemplate(skillPath: string, manifest: PortableSkillManifest): void;
 /**

package/dist/lib/portable-skills-types.d.ts

@@ -98,6 +98,8 @@ export interface PortableSkillOptions {
 }
 export interface ScaffoldPortableSkillOptions extends PortableSkillOptions {
     description?: string;
+    category?: string;
+    tags?: string[];
     overwrite?: boolean;
     kind?: SkillKind;
 }

package/dist/lib/remote-account.d.ts

@@ -0,0 +1,42 @@
+import type { RemoteInputFileDescriptor } from "./remote-files.js";
+/** Optional account APIs supplied by a configured Skills server. No local prices or provider policy. */
+export interface RemoteRunQuote {
+    skill: string;
+    pricing: {
+        costCents: number;
+        formattedCost: string;
+        [key: string]: unknown;
+    };
+    [key: string]: unknown;
+}
+export interface RemoteRunApproval {
+    /** Preferred public spelling: maximum integer credits approved by the caller. */
+    maxCredits?: number;
+    /** Maximum integer credits approved by the caller (legacy wire spelling). */
+    maxCostCents?: number;
+    idempotencyKey?: string;
+    inputFiles?: RemoteInputFileDescriptor[];
+}
+export interface RemoteCreditPack {
+    id: string;
+    credits: number;
+    expiresInDays?: number;
+}
+export declare class RemoteCreditApprovalError extends Error {
+    readonly requiredCredits: number;
+    readonly maximumCredits: number;
+    readonly code = "CREDIT_APPROVAL_REQUIRED";
+    constructor(requiredCredits: number, maximumCredits: number);
+}
+export declare function creditCount(value: unknown): number;
+export declare function parseRemoteRunQuote(value: unknown): RemoteRunQuote;
+export declare function parseRemoteCreditPacks(value: unknown): RemoteCreditPack[];
+export declare function parseRemoteBillingStatus(value: unknown): {
+    hasPaymentMethod?: boolean | undefined;
+    plan?: string | undefined;
+    creditBalance: number;
+    formattedCreditBalance: string;
+};
+export declare function parseRemoteCheckout(value: unknown): {
+    url: string;
+};

package/dist/lib/remote-auth.d.ts

@@ -0,0 +1,32 @@
+export declare class HostedApiError extends Error {
+    readonly status?: number;
+    readonly code?: string;
+    readonly detail?: string;
+    readonly endpoint?: string;
+    readonly apiUrl?: string;
+    constructor(message: string, options?: {
+        status?: number;
+        code?: string;
+        detail?: string;
+        endpoint?: string;
+        apiUrl?: string;
+    });
+}
+/** Passwordless auth transport for an explicitly selected instance. It never writes credentials. */
+export declare class RemoteSkillsAuthClient {
+    readonly apiOrigin: string;
+    constructor(apiUrl: string);
+    requestCode(email: string): Promise<any>;
+    verifyCode(email: string, code: string): Promise<any>;
+    startDevice(): Promise<any>;
+    pollDevice(deviceCode: string): Promise<any>;
+    private sessionClient;
+    createApiKey(email: string, code: string, name: string, scopes?: string[]): Promise<{
+        [field: string]: unknown;
+        key: string;
+    }>;
+    listApiKeys(email: string, code: string): Promise<Record<string, unknown>[]>;
+    revokeApiKey(email: string, code: string, keyId: string): Promise<Record<string, unknown>>;
+    /** Common auth transport used by CLI login, preserving the selected instance through awaits. */
+    request(path: string, options?: RequestInit): Promise<any>;
+}

package/dist/lib/remote-client.d.ts

@@ -1,4 +1,6 @@
 import { type RemoteSkillRunContract } from "./remote-run-contract.js";
+import { type RemoteCreditPack, type RemoteRunApproval, type RemoteRunQuote } from "./remote-account.js";
+import { type RemoteInputFile } from "./remote-files.js";
 /**
  * A server that predates this client's pin/tag/incremental-sync routes answered
  * 404/405 for them. The caller must never mistake that for "no pins" or "empty
@@ -55,6 +57,7 @@ export interface UpdatedSincePage {
 export declare class RemoteSkillsClient {
     private apiUrl;
     private apiKey;
+    private capabilities?;
     constructor(apiKey: string, apiUrl?: string);
     private request;
     /**
@@ -88,12 +91,64 @@ export declare class RemoteSkillsClient {
         status: number;
         body: unknown;
     }>;
-    submitRun(slug: string, input?: Record<string, unknown>, args?: string[]): Promise<RemoteSkillRunContract>;
+    /** Low-level admission transport; interactive surfaces use submitQuotedRun. */
+    submitRun(slug: string, input?: Record<string, unknown>, args?: string[], approval?: RemoteRunApproval): Promise<RemoteSkillRunContract>;
+    quoteRun(slug: string, input?: Record<string, unknown>, args?: string[]): Promise<RemoteRunQuote>;
+    getCapabilities(): Promise<{
+        contractVersion: 1;
+        apiVersion: 1;
+        capabilities: string[];
+        billing?: {
+            boundedRunApproval?: boolean;
+            unit?: string;
+        };
+    }>;
+    /** Quote first and fail closed when the caller has not approved the required credits. */
+    submitQuotedRun(slug: string, input?: Record<string, unknown>, args?: string[], approval?: RemoteRunApproval): Promise<RemoteSkillRunContract>;
+    getIdentity(): Promise<Record<string, unknown>>;
+    listApiKeys(): Promise<Record<string, unknown>[]>;
+    createApiKey(name: string, scopes?: string[]): Promise<{
+        key: string;
+        [field: string]: unknown;
+    }>;
+    revokeApiKey(keyId: string): Promise<Record<string, unknown>>;
+    getBillingStatus(): Promise<{
+        hasPaymentMethod?: boolean | undefined;
+        plan?: string | undefined;
+        creditBalance: number;
+        formattedCreditBalance: string;
+    }>;
+    listCreditPacks(): Promise<RemoteCreditPack[]>;
+    createCreditCheckout(packId: string): Promise<{
+        url: string;
+    }>;
+    getUsage(): Promise<Record<string, unknown>[]>;
+    listInvoices(): Promise<Record<string, unknown>[]>;
+    createBillingCheckout(): Promise<{
+        url: string;
+    }>;
+    createBillingPortal(): Promise<{
+        url: string;
+    }>;
+    cancelRun(runId: string): Promise<RemoteSkillRunContract>;
+    resumeRun(runId: string): Promise<RemoteSkillRunContract>;
+    private controlRun;
+    private checkoutResponse;
+    private arrayResponse;
     getRun(runId: string): Promise<RemoteSkillRunContract | null>;
     getRunLogs(runId: string): Promise<any[]>;
     listRuns(limit?: number): Promise<any[]>;
     getRunArtifacts(runId: string): Promise<any[]>;
     downloadRunArtifact(runId: string, artifactId: string): Promise<Response>;
+    getVerifiedRunArtifact(runId: string, artifactId: string, maximumBytes?: number): Promise<{
+        id: string;
+        fileName: string;
+        bytes: Uint8Array<ArrayBufferLike>;
+        byteSize: number;
+        sha256: any;
+    }>;
+    submitQuotedRunWithFiles(slug: string, input: Record<string, unknown>, args: string[], files: RemoteInputFile[], approval?: RemoteRunApproval): Promise<RemoteSkillRunContract>;
+    uploadRunFiles(runId: string, files: RemoteInputFile[]): Promise<void>;
     /**
      * Publish a skill to the configured instance.
      *

package/dist/lib/remote-customer-operations.d.ts

@@ -0,0 +1,106 @@
+import type { RemoteSkillsClient } from "./remote-client.js";
+/** Shared customer operation declarations for MCP registration and its discovery contract. */
+export declare const REMOTE_CUSTOMER_OPERATIONS: readonly [{
+    readonly name: "get_account";
+    readonly title: "Get Account Identity";
+    readonly parameter: null;
+    readonly mutates: false;
+    readonly invoke: (client: RemoteSkillsClient) => Promise<Record<string, unknown>>;
+}, {
+    readonly name: "get_server_capabilities";
+    readonly title: "Get Server Capabilities";
+    readonly parameter: null;
+    readonly mutates: false;
+    readonly invoke: (client: RemoteSkillsClient) => Promise<{
+        contractVersion: 1;
+        apiVersion: 1;
+        capabilities: string[];
+        billing?: {
+            boundedRunApproval?: boolean;
+            unit?: string;
+        };
+    }>;
+}, {
+    readonly name: "list_remote_skills";
+    readonly title: "List Remote Skills";
+    readonly parameter: null;
+    readonly mutates: false;
+    readonly invoke: (client: RemoteSkillsClient) => Promise<any[]>;
+}, {
+    readonly name: "get_billing_status";
+    readonly title: "Get Billing Status";
+    readonly parameter: null;
+    readonly mutates: false;
+    readonly invoke: (client: RemoteSkillsClient) => Promise<{
+        hasPaymentMethod?: boolean | undefined;
+        plan?: string | undefined;
+        creditBalance: number;
+        formattedCreditBalance: string;
+    }>;
+}, {
+    readonly name: "list_credit_packs";
+    readonly title: "List Credit Packs";
+    readonly parameter: null;
+    readonly mutates: false;
+    readonly invoke: (client: RemoteSkillsClient) => Promise<import("./remote-account.js").RemoteCreditPack[]>;
+}, {
+    readonly name: "create_credit_checkout";
+    readonly title: "Create Credit Checkout";
+    readonly parameter: "pack_id";
+    readonly mutates: true;
+    readonly invoke: (client: RemoteSkillsClient, value: string) => Promise<{
+        url: string;
+    }>;
+}, {
+    readonly name: "get_billing_usage";
+    readonly title: "Get Billing Usage";
+    readonly parameter: null;
+    readonly mutates: false;
+    readonly invoke: (client: RemoteSkillsClient) => Promise<Record<string, unknown>[]>;
+}, {
+    readonly name: "list_invoices";
+    readonly title: "List Invoices";
+    readonly parameter: null;
+    readonly mutates: false;
+    readonly invoke: (client: RemoteSkillsClient) => Promise<Record<string, unknown>[]>;
+}, {
+    readonly name: "create_billing_checkout";
+    readonly title: "Create Billing Checkout";
+    readonly parameter: null;
+    readonly mutates: true;
+    readonly invoke: (client: RemoteSkillsClient) => Promise<{
+        url: string;
+    }>;
+}, {
+    readonly name: "create_billing_portal";
+    readonly title: "Create Billing Portal";
+    readonly parameter: null;
+    readonly mutates: true;
+    readonly invoke: (client: RemoteSkillsClient) => Promise<{
+        url: string;
+    }>;
+}, {
+    readonly name: "get_run_logs";
+    readonly title: "Get Run Logs";
+    readonly parameter: "run_id";
+    readonly mutates: false;
+    readonly invoke: (client: RemoteSkillsClient, value: string) => Promise<any[]>;
+}, {
+    readonly name: "cancel_run";
+    readonly title: "Cancel Run";
+    readonly parameter: "run_id";
+    readonly mutates: true;
+    readonly invoke: (client: RemoteSkillsClient, value: string) => Promise<import("./remote-run-contract.js").RemoteSkillRunContract>;
+}, {
+    readonly name: "resume_run";
+    readonly title: "Resume Run";
+    readonly parameter: "run_id";
+    readonly mutates: true;
+    readonly invoke: (client: RemoteSkillsClient, value: string) => Promise<import("./remote-run-contract.js").RemoteSkillRunContract>;
+}, {
+    readonly name: "list_run_artifacts";
+    readonly title: "List Run Artifacts";
+    readonly parameter: "run_id";
+    readonly mutates: false;
+    readonly invoke: (client: RemoteSkillsClient, value: string) => Promise<any[]>;
+}];

package/dist/lib/remote-files.d.ts

@@ -0,0 +1,21 @@
+export declare const MAX_REMOTE_FILE_BYTES: number;
+export interface RemoteInputFile {
+    name: string;
+    bytes: Uint8Array;
+    contentType?: string;
+}
+export interface RemoteInputFileDescriptor {
+    name: string;
+    sizeBytes: number;
+    sha256: string;
+    contentType: string;
+}
+export declare function describeRemoteFiles(files: RemoteInputFile[]): RemoteInputFileDescriptor[];
+export declare function sha256(bytes: Uint8Array): string;
+export declare function readBoundedResponse(response: Response, maximum: number): Promise<Uint8Array>;
+/** Small inline inputs for agent transports; larger files belong in the CLI/SDK. */
+export declare function decodeRemoteFiles(files: Array<{
+    name: string;
+    base64: string;
+    contentType?: string;
+}>): RemoteInputFile[];

package/dist/lib/run-routing.d.ts

@@ -35,6 +35,7 @@ export type RunRoutingErrorCode = "REMOTE_REQUIRES_ORIGIN" | "REMOTE_REQUIRES_CR
 export type RunRouting = {
     route: "remote";
     apiKey: string;
+    apiOrigin: string;
 } | {
     route: "local";
 } | {

package/dist/lib/run-state.d.ts

@@ -25,6 +25,8 @@ export interface SkillRunRecord {
     durationMs?: number;
     remote: boolean;
     remoteRunId?: string;
+    /** Exact configured instance that owns a remote run; absent on historical records. */
+    remoteApiOrigin?: string;
     costCents?: number;
     error?: string;
     artifacts: SkillRunArtifact[];
@@ -47,6 +49,7 @@ export declare function createSkillRun(params: {
     prompt?: string;
     remote?: boolean;
     remoteRunId?: string;
+    remoteApiOrigin?: string;
     costCents?: number;
     status?: SkillRunStatus;
 }, targetDir?: string): SkillRunContext;

package/dist/mcp/remote-customer-tools.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerRemoteCustomerTools(server: McpServer): void;

package/dist/sdk/index.d.ts

@@ -30,3 +30,7 @@ export * from "./events.js";
 export * from "./spend.js";
 export * from "./offline.js";
 export * from "./execution/index.js";
+export { RemoteSkillsClient, createRemoteSkillsClient, RemoteRequestError, RemoteRouteUnsupportedError } from "../lib/remote-client.js";
+export { RemoteCreditApprovalError, type RemoteRunApproval, type RemoteRunQuote, type RemoteCreditPack } from "../lib/remote-account.js";
+export { type RemoteInputFile, type RemoteInputFileDescriptor } from "../lib/remote-files.js";
+export { RemoteSkillsAuthClient, HostedApiError } from "../lib/remote-auth.js";