@hasna/skills 0.8.10 → 0.8.12

package/dist/lib/agent-discovery.d.ts

@@ -5,7 +5,7 @@ export { captureDiscoveryDirectories, type DiscoveryDirectory } from "./agent-di
 export interface DiscoverySource {
     path: string;
     sha256: string | null;
-    hashMode?: "bytes" | "path-bytes" | "claude-plugin-registry";
+    hashMode?: "bytes" | "path-bytes" | "claude-plugin-registry" | "claude-marketplace-registry" | "claude-settings-v1";
     managedPlugins?: ManagedPluginRegistrationWitness[];
     format?: "json" | "toml" | "yaml";
     fields?: string[];

package/dist/lib/claude-marketplace-registry.d.ts

@@ -0,0 +1,17 @@
+export declare const CLAUDE_MARKETPLACE_REGISTRY_LIMITS: Readonly<{
+    bytes: number;
+    rows: 1024;
+    depth: 32;
+    nodes: 65536;
+    stringCharacters: 16384;
+    pathCharacters: 4096;
+}>;
+export interface ClaudeMarketplaceRegistryBudget {
+    remaining: number;
+}
+/** Capture explicitly reviewed registry structure; never infer this mode from a raw-byte witness. */
+export declare function captureClaudeMarketplaceRegistry(path: string, budget?: ClaudeMarketplaceRegistryBudget): {
+    path: string;
+    hashMode: "claude-marketplace-registry";
+    sha256: string;
+};

package/dist/lib/claude-settings-witness.d.ts

@@ -0,0 +1,19 @@
+export declare const CLAUDE_SETTINGS_WITNESS_LIMITS: Readonly<{
+    bytes: number;
+    rows: 1024;
+    depth: 32;
+    nodes: 65536;
+    stringCharacters: 16384;
+    pathCharacters: 4096;
+}>;
+export interface ClaudeSettingsWitnessBudget {
+    remaining: number;
+}
+/** Hash only reviewed installer-rendered settings after the disk preimage has been verified. */
+export declare function hashClaudeSettingsReplacement(text: string, budget: ClaudeSettingsWitnessBudget): string;
+/** Explicit capture never converts a stored legacy raw witness or changes settings. */
+export declare function captureClaudeSettings(path: string, budget?: ClaudeSettingsWitnessBudget): {
+    path: string;
+    hashMode: "claude-settings-v1";
+    sha256: string;
+};

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

@@ -147,6 +147,24 @@ export declare class SkillsFleetCredentialError extends Error {
  * on the error's NAME rather than on a class identity a bundle may not share.
  */
 export declare function isSkillsFleetCredentialError(error: unknown): error is SkillsFleetCredentialError;
+/**
+ * Translate the shared seam's `CredentialResolutionError` into this package's
+ * own refusal, or return null for anything else.
+ *
+ * A DELIBERATE selection that cannot be honoured — `HASNA_PROFILE` naming a
+ * profile that has no entry, an override or pointer that resolves to nothing, a
+ * corrupt credentials file — is thrown by `@hasna/contracts`, not by the
+ * transport resolver. Left untranslated it escaped every helper in this file:
+ * `skillsCredentialOrReason` and `resolveConfiguredRunRouting` recognise only
+ * `SkillsFleetCredentialError`, so a `--json` command or an MCP tool got an
+ * unhandled exception where the structured refusal was the whole point.
+ *
+ * The seam's message already names what was attempted and never carries a
+ * credential value. Pointer-completion messages can still carry the selected
+ * vault item identifier, so that exact identifier is removed before the error
+ * reaches any user-visible surface.
+ */
+export declare const REDACTED_VAULT_REFERENCE = "[redacted vault reference]";
 /**
  * Normalize a configured Skills authority to the origin the client dials.
  *

package/dist/lib/hook-diagnostics.d.ts

@@ -0,0 +1,7 @@
+export declare class HookDiagnosticError extends Error {
+    readonly code: string;
+    readonly stage: "context" | "sync";
+    constructor(code: string, stage: "context" | "sync");
+}
+export declare function hookChildError(stdout: string, stage: "context" | "sync"): HookDiagnosticError;
+export declare function hookFailureReason(error: unknown, profileId?: string): string;

package/dist/lib/recurring-recovery.d.ts

@@ -62,7 +62,7 @@ export declare function readRecurringRecovery(directory: string): {
         operation: "revoke";
         consentId: string;
     };
-    phase: "pending" | "prepared" | "observed";
+    phase: "prepared" | "pending" | "observed";
     consentId: string | null;
 };
 export interface RecurringRecoveryOptions {
@@ -76,7 +76,7 @@ export declare function continueRecurringRecovery(customer: RecurringCustomer, d
     recoveryDirectory: string;
     operation: "activate" | "revoke";
     outcomeUnknown: boolean;
-    phase: "pending" | "prepared" | "observed";
+    phase: "prepared" | "pending" | "observed";
     result: unknown;
 }>;
 export {};

package/dist/lib/recurring-surface.d.ts

@@ -219,7 +219,7 @@ export declare function executeRecurringSurface(action: RecurringSurfaceAction,
     recoveryDirectory: string;
     operation: "activate" | "revoke";
     outcomeUnknown: boolean;
-    phase: "pending" | "prepared" | "observed";
+    phase: "prepared" | "pending" | "observed";
     result: unknown;
 } | {
     cancelled: boolean;

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

@@ -7,6 +7,7 @@ import { type RemoteWorkspaceMemberErrorCode, type SetRemoteWorkspaceMemberRole,
 import { type RemoteSkillRunContract } from "./remote-run-contract.js";
 import { type RemoteCreditPack, type RemoteRunApproval, type RemoteRunQuote } from "./remote-account.js";
 import { type RemoteInputFile, type RemoteInputFileDescriptor } from "./remote-files.js";
+import { type RemoteCreditCheckout, type RemoteCreditCheckoutOptions, type RemoteCreditCheckoutErrorCode } from "./remote-credit-checkout.js";
 import { type UpdateRemoteProfile, type UpdateRemoteWorkspace } from "./remote-profile.js";
 import { type RemoteQuoteUnavailableCode } from "./remote-quote-errors.js";
 import { type RemoteSkillsAccess } from "./remote-permissions.js";
@@ -29,6 +30,13 @@ export declare class RemoteRequestError extends Error {
     readonly status: number;
     constructor(path: string, status: number, _statusText?: string);
 }
+/** Bounded checkout outcome; the key is caller-owned, never copied from a server error. */
+export declare class RemoteCreditCheckoutError extends RemoteRequestError {
+    readonly code: RemoteCreditCheckoutErrorCode;
+    readonly requestIdempotencyKey: string;
+    readonly retryAfterSeconds?: number | undefined;
+    constructor(code: RemoteCreditCheckoutErrorCode, status: number, requestIdempotencyKey: string, retryAfterSeconds?: number | undefined);
+}
 /** A recognized unavailable quote; status compatibility and client-owned copy. */
 export declare class RemoteQuoteUnavailableError extends RemoteRequestError {
     readonly code: RemoteQuoteUnavailableCode;
@@ -196,9 +204,8 @@ export declare class RemoteSkillsClient {
         formattedCreditBalance: string;
     }>;
     listCreditPacks(): Promise<RemoteCreditPack[]>;
-    createCreditCheckout(packId: string): Promise<{
-        url: string;
-    }>;
+    /** One checkout POST. Retain an explicit key before calling to recover even a lost process. */
+    createCreditCheckout(packId: string, options?: RemoteCreditCheckoutOptions): Promise<RemoteCreditCheckout>;
     getUsage(): Promise<Record<string, unknown>[]>;
     listInvoices(): Promise<Record<string, unknown>[]>;
     createBillingCheckout(): Promise<{

package/dist/lib/remote-credit-checkout.d.ts

@@ -0,0 +1,22 @@
+/** Caller-owned checkout identity. Reuse only for the same server, account and pack. */
+export interface RemoteCreditCheckoutOptions {
+    idempotencyKey?: string;
+}
+export interface RemoteCreditCheckout {
+    url: string;
+    requestIdempotencyKey: string;
+}
+export declare const creditCheckoutKeyPattern: RegExp;
+export declare function creditCheckoutRequestKey(value: unknown): string;
+export declare const creditCheckoutMessages: {
+    readonly CREDIT_CHECKOUT_UNCONFIRMED: "Checkout creation could not be confirmed. Keep the request idempotency key, inspect billing, and use the same key for an explicit retry on the same server, account and pack. No automatic retry was made.";
+    readonly CREDIT_CHECKOUT_IN_PROGRESS: "This checkout is still being created. Wait before explicitly retrying the same server, account and pack with the same request idempotency key. No automatic retry was made.";
+    readonly CREDIT_CHECKOUT_EXPIRED: "This checkout has expired. Inspect billing before deliberately starting a new purchase with a new request idempotency key. Do not retry this checkout automatically.";
+    readonly CREDIT_CHECKOUT_FULFILLED: "This checkout is already fulfilled. Inspect the account balance; do not create another checkout to recover this purchase.";
+};
+export type RemoteCreditCheckoutErrorCode = keyof typeof creditCheckoutMessages;
+/** Only recognized server states become typed outcomes; never retain server text. */
+export declare function creditCheckoutFailure(value: unknown, status: number, key: string): {
+    code: RemoteCreditCheckoutErrorCode;
+    retryAfterSeconds?: number;
+};

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

@@ -1,3 +1,4 @@
+import type { RemoteCreditCheckoutOptions } from "./remote-credit-checkout.js";
 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 [{
@@ -49,9 +50,7 @@ export declare const REMOTE_CUSTOMER_OPERATIONS: readonly [{
     readonly title: "Create Credit Checkout";
     readonly parameter: "pack_id";
     readonly mutates: true;
-    readonly invoke: (client: RemoteSkillsClient, value: string) => Promise<{
-        url: string;
-    }>;
+    readonly invoke: (client: RemoteSkillsClient, value: string, options?: RemoteCreditCheckoutOptions) => Promise<import("./remote-credit-checkout.js").RemoteCreditCheckout>;
 }, {
     readonly name: "get_billing_usage";
     readonly title: "Get Billing Usage";

package/dist/lib/selection-cache.d.ts

@@ -13,9 +13,28 @@ export interface CachedSelectionProfile {
     verifiedAt: string;
     profile: ResolvedSkillProfile;
 }
+export interface SkillSessionParentBinding {
+    sessionId: string;
+    generation: number;
+    receiptSha256: string;
+}
 export interface SkillSessionReceipt extends CachedSelectionProfile {
     sessionId: string;
     loaded: string[];
+    /** Monotonic across sanctioned receipt writes. Legacy receipts without it are generation zero. */
+    generation?: number;
+    /** Private local metadata binding a child receipt to the exact parent snapshot it inherited. */
+    parent?: SkillSessionParentBinding;
+}
+export interface SkillSessionSnapshot extends SkillSessionParentBinding {
+    path: string;
+    bytes: Uint8Array;
+    receipt: SkillSessionReceipt;
+    sha256: string;
+}
+export interface SkillSessionWritePrecondition {
+    current: SkillSessionParentBinding | null;
+    parent?: SkillSessionParentBinding;
 }
 export declare const MAX_CACHED_PROFILE_AGE_MS: number;
 export declare const SELECTION_LOCK_FILE = "selection.lock.json";
@@ -38,3 +57,16 @@ export declare function projectSelectionLockPath(projectDir: string): string;
 export declare function readProjectSelection(projectDir: string): CachedSelectionProfile | null;
 export declare function sessionReceiptPath(sessionId: string, options?: SelectionCacheOptions): string;
 export declare function readSkillSession(sessionId: string, options?: SelectionCacheOptions): SkillSessionReceipt | null;
+export declare function readSkillSessionSnapshotIfExists(sessionId: string, options?: SelectionCacheOptions): SkillSessionSnapshot | null;
+export declare function readSkillSessionSnapshot(sessionId: string, options?: SelectionCacheOptions): SkillSessionSnapshot;
+export declare function skillSessionSnapshotBinding(snapshot: SkillSessionSnapshot): SkillSessionParentBinding;
+export declare function nextSkillSessionGeneration(generation: number): number;
+/** Receipt creation and updates are exact-snapshot CAS operations. Child creation also fences its parent. */
+export declare function writeSkillSession(receipt: SkillSessionReceipt, expected: SkillSessionWritePrecondition, options?: SelectionCacheOptions): void;
+/** Preserve both sides before the single atomic replacement; failures retain recovery evidence. */
+export declare function replaceSkillSession(expected: SkillSessionParentBinding, replacement: SkillSessionReceipt, plan: unknown, options?: SelectionCacheOptions, beforeCommit?: () => void): {
+    archivePath: string;
+    receiptPath: string;
+    beforeSha256: string;
+    afterSha256: string;
+};

package/dist/lib/selection-resolver.d.ts

@@ -2,7 +2,7 @@
 import { type ProfileClient } from "./profile-client.js";
 import type { ResolvedSkillProfile, ResolvedSkillSelection } from "../types/skill-selection.js";
 import type { SkillBundleEntry } from "./skill-bundle.js";
-import { type CachedSelectionProfile, type SelectionCacheOptions, type SkillSessionReceipt } from "./selection-cache.js";
+import { type CachedSelectionProfile, type SelectionCacheOptions, type SkillSessionParentBinding, type SkillSessionReceipt } from "./selection-cache.js";
 export interface SelectionResolverOptions extends SelectionCacheOptions {
     client?: ProfileClient;
     cached?: boolean;
@@ -31,6 +31,8 @@ export declare function syncSelectionProfile(profileId: string, options?: SyncSe
 export interface ResolvedSelectionContext {
     receipt: CachedSelectionProfile;
     session: SkillSessionReceipt | null;
+    sessionSnapshot: SkillSessionParentBinding | null;
+    parentSnapshot?: SkillSessionParentBinding;
     inheritedLoaded?: string[];
     client?: ProfileClient;
 }

package/dist/lib/session-reconciliation.d.ts

@@ -0,0 +1,100 @@
+import { type ProfileClient } from "./profile-client.js";
+import { type SelectionCacheOptions } from "./selection-cache.js";
+export interface SessionReconciliationInput {
+    sessionId: string;
+    fromProfile: string;
+    fromRevision: string;
+    receiptSha256: string;
+    selectionProfile: string;
+    profileRevision: string;
+    apply?: boolean;
+    planDigest?: string;
+    planIssuedAt?: string;
+    planExpiresAt?: string;
+}
+export interface SessionReconciliationOptions extends SelectionCacheOptions {
+    client?: ProfileClient;
+}
+export declare const SESSION_RECONCILIATION_PLAN_TTL_MS: number;
+/** Metadata only: inspection never displays skill payloads or resolves credentials. */
+export declare function inspectSkillSession(sessionId: string, options?: SelectionCacheOptions): {
+    sessionId: string;
+    path: string;
+    receiptSha256: string;
+    generation: number;
+    verifiedAt: string;
+    authority: string;
+    workspaceId: string;
+    profileId: string;
+    profileRevision: string;
+    selectionCount: number;
+    loadedCount: number;
+};
+/** Explicit opt-in only. Ordinary loads and hooks retain their immutable session pins. */
+export declare function reconcileSkillSession(input: SessionReconciliationInput, options?: SessionReconciliationOptions): Promise<{
+    applied: false;
+    plan: {
+        schemaVersion: number;
+        issuedAt: string;
+        expiresAt: string;
+        sessionId: string;
+        sessionPath: string;
+        before: {
+            receiptSha256: string;
+            generation: number;
+            profileId: string;
+            profileRevision: string;
+            selectionCount: number;
+        };
+        target: {
+            authority: string;
+            workspaceId: string;
+            profileId: string;
+            profileRevision: string;
+            profileSha256: string;
+            selectionCount: number;
+        };
+        replacementGeneration: number;
+        retainedLoadedCount: number;
+        retiredLoadedCount: number;
+        scope: string;
+    };
+    planDigest: string;
+    archivePath: undefined;
+    receiptPath: undefined;
+    beforeSha256: string;
+    afterSha256: undefined;
+} | {
+    archivePath: string;
+    receiptPath: string;
+    beforeSha256: string;
+    afterSha256: string;
+    applied: true;
+    plan: {
+        schemaVersion: number;
+        issuedAt: string;
+        expiresAt: string;
+        sessionId: string;
+        sessionPath: string;
+        before: {
+            receiptSha256: string;
+            generation: number;
+            profileId: string;
+            profileRevision: string;
+            selectionCount: number;
+        };
+        target: {
+            authority: string;
+            workspaceId: string;
+            profileId: string;
+            profileRevision: string;
+            profileSha256: string;
+            selectionCount: number;
+        };
+        replacementGeneration: number;
+        retainedLoadedCount: number;
+        retiredLoadedCount: number;
+        scope: string;
+    };
+    planDigest: string;
+}>;

package/dist/sdk/index.d.ts

@@ -18,6 +18,7 @@
 export { readExecutionGrantPolicy, saveExecutionGrantPolicy, resolveExecutionGrant } from "../lib/execution-grant-client.js";
 export type { ExecutionGrant, ExecutionGrantPolicy, ExecutionGrantRequest, ResolvedExecutionGrant } from "../lib/execution-grants.js";
 export { HttpProfileClient, createProfileClient, type ProfileClient, type AuthenticatedProfilePrincipal, type AuthenticatedProfileRole } from "../lib/profile-client.js";
+export { inspectSkillSession, reconcileSkillSession, type SessionReconciliationInput, type SessionReconciliationOptions } from "../lib/session-reconciliation.js";
 export { resolveSelectedRun, executeSelectedLocal, prepareSelectedSecretBindings, type ResolvedSelectedRun, type SelectedLocalRunOptions } from "../lib/selected-run.js";
 export { readSelectedSecretBindings, type SelectedSecretBindings, type SelectedSecretsClient } from "../lib/execution-secrets.js";
 export type { SkillSelection, SkillProfile, ResolvedSkillSelection, ResolvedSkillProfile, StationSkillStateInput, StationSkillState } from "../types/skill-selection.js";
@@ -36,7 +37,7 @@ export * from "./events.js";
 export * from "./spend.js";
 export * from "./offline.js";
 export * from "./execution/index.js";
-export { RemoteSkillsClient, createRemoteSkillsClient, RemoteRequestError, RemoteRouteUnsupportedError, RemoteCapabilityUnavailableError, RemoteQuoteUnavailableError, RemoteWorkspaceMemberError } from "../lib/remote-client.js";
+export { RemoteSkillsClient, createRemoteSkillsClient, RemoteRequestError, RemoteCreditCheckoutError, RemoteRouteUnsupportedError, RemoteCapabilityUnavailableError, RemoteQuoteUnavailableError, RemoteWorkspaceMemberError } from "../lib/remote-client.js";
 export { RemoteSkillsPermissionError, type RemoteSkillsAccess, type RemoteSkillsPermissions } from "../lib/remote-permissions.js";
 export * from "../lib/remote-recurring-contract.js";
 export { RecurringInputError, RemoteRecurringError, RemoteRecurringUnavailableError, RemoteRecurringReadError, RemoteRecurringUnconfirmedError } from "../lib/remote-recurring.js";
@@ -60,3 +61,4 @@ export { InvitationEmailInputError, RemoteInvitationEmailError, RemoteInvitation
 export { RemotePrivatePublicationsClient, PrivatePublicationError, PRIVATE_PUBLICATION_MAX_BYTES, type PrivatePublicationDeclaration, type PrivatePublicationView, type PrivatePublicationState, type PrivatePublishingCapability } from "../lib/remote-private-publications.js";
 export { preparePrivatePublication, readPrivatePublicationRecovery, continuePrivatePublication, inspectPrivatePublication, type PrivatePublicationRecovery, type PrivatePublicationResult } from "../lib/private-publication-recovery.js";
 export { createSkillOperationClient, SkillOperationClientError, SKILL_OPERATION_LIMITS, type SkillOperationClient, type SkillOperationTransport, type SkillOperationRequest, type SkillOperationResult, type SkillOperationJson, type SkillOperationRefusal, type SkillOperationClientErrorCode } from "./operations.js";
+export type { RemoteCreditCheckoutOptions, RemoteCreditCheckout, RemoteCreditCheckoutErrorCode } from "../lib/remote-credit-checkout.js";