@hasna/skills 0.5.3 → 0.5.5

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

@@ -124,7 +124,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" | "INSTANCE_CREDENTIAL_MISMATCH";
+export type SkillsFleetErrorCode = "MISSING_API_CREDENTIAL" | "INVALID_API_URL" | "INSTANCE_CREDENTIAL_MISMATCH" | "GATEWAY_AUTH_UNAVAILABLE";
 /**
  * A configured install could not produce a usable hosted client.
  *
@@ -155,6 +155,11 @@ export declare function isSkillsFleetCredentialError(error: unknown): error is S
  * URL printed by every error message — must not end up with `/api/v1/api/v1`.
  */
 export declare function normalizeSkillsApiOrigin(apiUrl: string): string;
+/** Compose a known Skills route without changing its credential-bound instance.
+ * The fleet gateway strips /skills and forwards /v1 to its independent origin.
+ * Other instances retain the established /api/v1 and /api/auth contracts.
+ */
+export declare function skillsApiRequestUrl(apiUrl: string, route: string): string;
 /** One configured authority: its value and the source that decided it. */
 export interface ConfiguredSkillsApiUrl {
     value: string;

package/dist/lib/home-adoption.d.ts

@@ -74,8 +74,8 @@ export declare function indexCanonicalCorpus(corpusRoot: string): Map<string, st
 export declare function scanUnmarkedHomes(options?: AdoptionOptions): AdoptionScan;
 /**
  * Write one rollback record listing every marker written (mode "adopt") or
- * every directory removed (mode "prune"), so both operations are reversible
- * from a single machine-readable file.
+ * every directory removed (mode "prune"), so both operations are auditable
+ * from a single machine-readable file. Deleted resource bytes are not stored.
  */
 export declare function writeRollbackRecord(mode: "adopt" | "prune", entries: RollbackMarker[], appDir?: string): string;
 /**
@@ -85,9 +85,4 @@ export declare function writeRollbackRecord(mode: "adopt" | "prune", entries: Ro
  * records every written marker in a rollback file. Never deletes anything.
  */
 export declare function adoptUnmarkedHomes(options?: AdoptionOptions): AdoptionResult;
-/**
- * List (or, with `apply`, remove) marked home skill dirs that have no canonical
- * corpus entry. Never touches an unmarked directory. Removals are recorded in
- * the rollback store before they happen.
- */
 export declare function pruneStrayHomes(options?: AdoptionOptions): PruneResult;

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

@@ -13,6 +13,7 @@ export interface JsonSchemaObject {
     pattern?: string;
     maxItems?: number;
     maxLength?: number;
+    minLength?: number;
     items?: JsonSchemaObject;
     properties?: Record<string, JsonSchemaObject>;
     required?: string[];

package/dist/lib/private-publication-customer.d.ts

@@ -0,0 +1,10 @@
+import { RemotePrivatePublicationsClient } from "./remote-private-publications.js";
+import type { RemoteWorkspaceContext } from "./remote-workspace-selection.js";
+/** Capture host profile before fresh verification. Neither the session nor a
+ * signed upload capability is written to the host's credentials. */
+export declare function privatePublicationSession(email: string, code: string, requested?: RemoteWorkspaceContext): Promise<RemotePrivatePublicationsClient>;
+export declare function privatePublicationCustomerError(error: unknown): {
+    error: string;
+    code: string;
+    uncertain: boolean;
+};

package/dist/lib/private-publication-recovery.d.ts

@@ -0,0 +1,43 @@
+import { RemotePrivatePublicationsClient, type PrivatePublicationDeclaration, type PrivatePublicationView } from "./remote-private-publications.js";
+type Phase = "prepared" | "begin_uncertain" | "awaiting_upload" | "upload_uncertain" | "uploaded" | "finalize_uncertain" | "observed";
+export interface PrivatePublicationRecovery {
+    contractVersion: 1;
+    apiOrigin: string;
+    organizationId: string;
+    userId: string;
+    membershipId: string;
+    skillId: string;
+    declaration: PrivatePublicationDeclaration;
+    phase: Phase;
+    intent: PrivatePublicationView | null;
+}
+export interface PrivatePublicationResult {
+    recoveryDirectory: string;
+    skillId: string;
+    intentId: string | null;
+    state: string;
+    versionId: string | null;
+    committed: boolean;
+    executionEnabled: false;
+    nextAction: string;
+}
+/** Reads only two bounded local files. The receipt never contains a token or signed URL. */
+export declare function readPrivatePublicationRecovery(directory: string): {
+    receipt: PrivatePublicationRecovery;
+    bytes: Buffer;
+};
+/** Snapshot and verify before the first publication request. Source files are not rewritten. */
+export declare function preparePrivatePublication(client: RemotePrivatePublicationsClient, sourceDirectory: string, recoveryDirectory: string, input: {
+    skillId: string;
+    expectedCurrentVersionId: string | null;
+    idempotencyKey?: string;
+}): Promise<PrivatePublicationRecovery>;
+export declare function privatePublicationResult(directory: string, receipt: PrivatePublicationRecovery): PrivatePublicationResult;
+/** Each write-ahead phase is durable before its network mutation. A resumed
+ * uncertain PUT is finalized for server verification, never uploaded again. */
+export declare function continuePrivatePublication(client: RemotePrivatePublicationsClient, directory: string, options: {
+    confirm: true;
+    waitMs?: number;
+}): Promise<PrivatePublicationResult>;
+export declare function inspectPrivatePublication(client: RemotePrivatePublicationsClient, directory: string, cancel?: boolean): Promise<PrivatePublicationResult>;
+export {};

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

@@ -2,6 +2,8 @@ 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;
+    /** Opaque server binding for this exact quote; retain verbatim for approval. */
+    quoteReceipt?: string;
     pricing: {
         costCents: number;
         formattedCost: string;
@@ -10,6 +12,8 @@ export interface RemoteRunQuote {
     [key: string]: unknown;
 }
 export interface RemoteRunApproval {
+    /** A previously quoted server binding. Never refresh it after user approval. */
+    quoteReceipt?: string;
     /** Preferred public spelling: maximum integer credits approved by the caller. */
     maxCredits?: number;
     /** Maximum integer credits approved by the caller (legacy wire spelling). */
@@ -29,6 +33,7 @@ export declare class RemoteCreditApprovalError extends Error {
     constructor(requiredCredits: number, maximumCredits: number);
 }
 export declare function creditCount(value: unknown): number;
+export declare function runQuoteReceipt(value: unknown): string | undefined;
 export declare function parseRemoteRunQuote(value: unknown): RemoteRunQuote;
 export declare function parseRemoteCreditPacks(value: unknown): RemoteCreditPack[];
 export declare function parseRemoteBillingStatus(value: unknown): {

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

@@ -1,4 +1,5 @@
 import { type RequestInvitationEmailChallenge, type AcceptInvitationEmailChallenge } from "./remote-invitation-recovery.js";
+import { RemotePrivatePublicationsClient } from "./remote-private-publications.js";
 import { type ListRemoteWorkspaceInvitations, type IssueRemoteWorkspaceInvitation, type ResendRemoteWorkspaceInvitation, type RevokeRemoteWorkspaceInvitation, type AcceptRemoteWorkspaceInvitation } from "./remote-invitations.js";
 import { type LeaveRemoteWorkspace } from "./remote-workspace-leave.js";
 import { type RemoteWorkspaceContext, type RemoteWorkspaceSession, type RemoteAccountWorkspaceDiscovery } from "./remote-workspace-selection.js";
@@ -23,6 +24,8 @@ export declare class HostedApiError extends Error {
 export declare class RemoteSkillsAuthClient {
     readonly apiOrigin: string;
     constructor(apiUrl: string);
+    /** One fresh workspace-bound session for an entire publication. No credentials are saved. */
+    openPrivatePublications(email: string, code: string, context: RemoteWorkspaceContext): Promise<RemotePrivatePublicationsClient>;
     requestInvitationEmailChallenge(input: RequestInvitationEmailChallenge): Promise<import("./remote-invitation-recovery.js").RemoteInvitationEmailChallenge>;
     acceptInvitationEmailChallenge(input: AcceptInvitationEmailChallenge): Promise<import("./remote-invitation-recovery.js").RemoteInvitationEmailAcceptance>;
     requestCode(email: string): Promise<any>;

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

@@ -5,8 +5,10 @@ import { type RemoteWorkspaceMembersOptions, type RemoteWorkspaceMembersPage } f
 import { type RemoteWorkspaceMemberErrorCode, type SetRemoteWorkspaceMemberRole, type RemoveRemoteWorkspaceMember, type RemoteWorkspaceMemberRoleResult, type RemoteWorkspaceMemberRemovalResult } from "./remote-workspace.js";
 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";
+import { type RemoteInputFile, type RemoteInputFileDescriptor } from "./remote-files.js";
 import { type UpdateRemoteProfile, type UpdateRemoteWorkspace } from "./remote-profile.js";
+import { type RemoteQuoteUnavailableCode } from "./remote-quote-errors.js";
+export type { RemoteQuoteUnavailableCode } from "./remote-quote-errors.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
@@ -25,6 +27,11 @@ export declare class RemoteRequestError extends Error {
     readonly status: number;
     constructor(path: string, status: number, _statusText?: string);
 }
+/** A recognized unavailable quote; status compatibility and client-owned copy. */
+export declare class RemoteQuoteUnavailableError extends RemoteRequestError {
+    readonly code: RemoteQuoteUnavailableCode;
+    constructor(path: string, code: RemoteQuoteUnavailableCode);
+}
 /** A recognized membership refusal, with fixed text and no server payload. */
 export declare class RemoteWorkspaceMemberError extends RemoteRequestError {
     readonly code: RemoteWorkspaceMemberErrorCode;
@@ -114,7 +121,7 @@ export declare class RemoteSkillsClient {
     }>;
     /** 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>;
+    quoteRun(slug: string, input?: Record<string, unknown>, args?: string[], files?: RemoteInputFileDescriptor[]): Promise<RemoteRunQuote>;
     getCapabilities(): Promise<{
         contractVersion: 1;
         apiVersion: 1;

package/dist/lib/remote-private-publications.d.ts

@@ -0,0 +1,74 @@
+import { type RemoteWorkspaceSession } from "./remote-workspace-selection.js";
+export declare const PRIVATE_PUBLICATION_MAX_BYTES: number;
+export type PrivatePublicationState = "awaiting_upload" | "queued" | "verifying" | "needs_attention" | "committed" | "rejected" | "cancelled" | "expired";
+export interface PrivatePublicationDeclaration {
+    idempotencyKey: string;
+    version: string;
+    expectedCurrentVersionId: string | null;
+    manifestText: string;
+    archiveSha256: string;
+    archiveByteSize: number;
+}
+export interface PrivatePublicationView {
+    id: string;
+    skillId: string;
+    version: string;
+    expectedCurrentVersionId: string | null;
+    archiveSha256: string;
+    archiveByteSize: number;
+    state: PrivatePublicationState;
+    expiresAt: string;
+    createdAt: string;
+    versionId: string | null;
+}
+export interface PrivatePublishingCapability {
+    contractVersion: 1;
+    enabled: boolean;
+    authentication: "interactive-session";
+    maxArchiveBytes: 16777216;
+    uploadMaxTtlSeconds: 300;
+    executionEnabled: false;
+}
+/** Contains a short-lived bearer capability. Never print or persist this object. */
+export interface PrivatePublicationUpload {
+    method: "PUT";
+    uploadUrl: string;
+    headers: Readonly<Record<string, string>>;
+    expiresAt: string;
+}
+export declare class PrivatePublicationError extends Error {
+    readonly code: string;
+    readonly uncertain: boolean;
+    readonly status?: number | undefined;
+    constructor(code: string, message: string, uncertain?: boolean, status?: number | undefined);
+}
+export declare const publicationUuid: (v: unknown) => v is string;
+export declare const publicationSha256: (bytes: Uint8Array | string) => string;
+export declare function checkedPublicationDeclaration(value: unknown): PrivatePublicationDeclaration;
+export declare function checkedPublicationView(value: unknown, skillId: string, intentId?: string, declaration?: PrivatePublicationDeclaration): PrivatePublicationView;
+/** Explicit hosted contract, unrelated to registry publishSkill and its content revisions.
+ * Session tokens stay in private fields and are never written to credentials. */
+export declare class RemotePrivatePublicationsClient {
+    #private;
+    readonly apiOrigin: string;
+    readonly organizationId: string;
+    readonly userId: string;
+    readonly membershipId: string;
+    constructor(apiUrl: string, session: RemoteWorkspaceSession);
+    getCapability(options?: {
+        timeoutMs?: number;
+        signal?: AbortSignal;
+    }): Promise<PrivatePublishingCapability>;
+    begin(skillId: string, input: PrivatePublicationDeclaration): Promise<PrivatePublicationView>;
+    get(skillId: string, intentId: string, options?: {
+        timeoutMs?: number;
+        signal?: AbortSignal;
+    }): Promise<PrivatePublicationView>;
+    finalize(skillId: string, intentId: string): Promise<PrivatePublicationView>;
+    cancel(skillId: string, intentId: string): Promise<PrivatePublicationView>;
+    upload(skillId: string, intent: PrivatePublicationView, bytes: Uint8Array): Promise<void>;
+    wait(skillId: string, intentId: string, options?: {
+        timeoutMs?: number;
+        signal?: AbortSignal;
+    }): Promise<PrivatePublicationView>;
+}

package/dist/lib/remote-quote-errors.d.ts

@@ -0,0 +1,12 @@
+/** Client-owned copy only. Server error strings and details are never displayed. */
+export declare const quoteUnavailableMessages: Readonly<{
+    HOSTED_PROVIDER_UNAVAILABLE: "Hosted execution is temporarily unavailable on this Skills instance.";
+    HOSTED_CONNECTORS_UNAVAILABLE: "Hosted connector execution is unavailable on this Skills instance.";
+    SKILL_IMPLEMENTATION_UNAVAILABLE: "This skill has no hosted execution implementation.";
+    HOSTED_PRICING_UNAVAILABLE: "Hosted execution is unavailable while this skill's pricing is reviewed.";
+    RUNTIME_ALLOWLIST_REQUIRED: "Hosted execution is unavailable until this Skills instance enables its skill catalog.";
+    RUNTIME_SKILL_NOT_ALLOWED: "This skill is not enabled for hosted execution on this Skills instance.";
+}>;
+export type RemoteQuoteUnavailableCode = keyof typeof quoteUnavailableMessages;
+/** Read one small error body, bounded even when a peer sends headers then stalls. */
+export declare function readQuoteUnavailableCode(response: Response): Promise<RemoteQuoteUnavailableCode | null>;

package/dist/mcp/private-publication-tools.d.ts

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

package/dist/sdk/execution/dispatchers/ecs.d.ts

@@ -4,7 +4,7 @@
  * Implements the sdk `Dispatcher` interface (submit/cancel) with the launch
  * machinery the interface seam leaves to this module:
  *
- *  1. CAS-claim the next attempt's `attempt_id` + `lease_generation`
+ *  1. generation-check the attempt's `attempt_id` + `lease_generation`
  *     (stale generation rejected),
  *  2. persist the launch intent (clientToken, startedBy, request digest)
  *     BEFORE calling ECS,
@@ -12,12 +12,16 @@
  *     (run_id, attempt_id) and an immutable request digest,
  *  4. on a lost RunTask response, reconcile the SAME token — list tasks by
  *     startedBy, describe them — before any new attempt; a new attempt is
- *     forbidden until the previous launch is proven absent or terminal.
+ *     forbidden while the existing attempt remains unresolved.
  *
  * The AWS SDK is never called from tests: the `EcsRunTaskClient` interface is
  * the seam, `createAwsEcsClient` is the only place the real SDK is imported,
  * and every test injects a mock client.
  *
+ * Cross-process fencing requires a store with atomic transactional claims and
+ * transitions. The generic state machine's separate reads and writes alone do
+ * not establish that guarantee.
+ *
  * Nothing here names a concrete cluster, task definition, subnet, or account:
  * all infrastructure identifiers come from configuration (R4).
  */
@@ -26,6 +30,7 @@ import type { RunExecutionStore } from "../storage.js";
 import type { AttemptRecord, FrozenAdmission } from "../types.js";
 import { type RunStateMachine } from "../state-machine.js";
 import { type ReceiptService } from "../receipts.js";
+import { DescribeTasksCommand, ListTasksCommand, RunTaskCommand, StopTaskCommand } from "@aws-sdk/client-ecs";
 /** ClientToken bound: ECS RunTask accepts up to 32 ASCII characters. */
 export declare const CLIENT_TOKEN_BYTES = 16;
 export interface EcsTaskState {
@@ -126,26 +131,32 @@ export declare class EcsDispatcher implements Dispatcher {
     constructor(config: EcsDispatcherConfig, client: EcsRunTaskClient, options: EcsDispatcherOptions);
     /** sdk Dispatcher surface: submit an ADMITTED run (execution domain) to the launch machinery. */
     submit(run: FrozenAdmission): Promise<DispatchResult>;
-    /** sdk Dispatcher surface: fence the current generation and stop the task. */
+    /** Confirm the task stopped before recording cancellation and its receipt. */
     cancel(runId: string): Promise<DispatchResult>;
     /**
      * Launch the next attempt of a run.
      *
      * A previous attempt whose launch outcome is unknown (launching / ambiguous /
-     * launched) is reconciled FIRST. Only when the previous launch is proven
-     * absent or terminal is a new attempt minted and claimed.
+     * launched) is reconciled FIRST. Missing observations remain ambiguous;
+     * terminal observations return to the owner without minting another attempt.
      */
     launchAttempt(runId: string): Promise<LaunchOutcome>;
-    /** Reconcile an attempt whose launch outcome is unknown. */
+    /** ECS is eventually consistent: empty lists and missing descriptions cannot
+     * prove absence. Only an exact recognized observation can change launch state. */
     reconcile(admission: FrozenAdmission, attempt: AttemptRecord): Promise<LaunchOutcome>;
-    /** Resolve the task arn for the current attempt, reconciling if needed. */
-    private resolveTaskArn;
     private runTaskInput;
+    private cancellationReceipt;
     private writeCancellationReceipt;
 }
-/**
- * The one place the real AWS SDK is wired in. Returns a client bound to the
- * configured region; credentials resolve through the standard SDK chain.
- * Tests never construct this — they inject a mock `EcsRunTaskClient`.
- */
-export declare function createAwsEcsClient(region: string): EcsRunTaskClient;
+/** Injectable command transport exercises the actual AWS command adapter without network. */
+export interface EcsCommandTransport {
+    send(command: RunTaskCommand | ListTasksCommand | DescribeTasksCommand | StopTaskCommand): Promise<unknown>;
+}
+export interface AwsEcsClientOptions {
+    cluster?: string;
+    transport?: EcsCommandTransport;
+}
+/** Pass an explicit cluster when restoring an existing named-cluster attempt.
+ * The legacy one-argument factory binds to the first operation's cluster; read
+ * operations before RunTask retain AWS's default-cluster behavior. */
+export declare function createAwsEcsClient(region: string, options?: AwsEcsClientOptions): EcsRunTaskClient;

package/dist/sdk/index.d.ts

@@ -30,7 +30,8 @@ export * from "./events.js";
 export * from "./spend.js";
 export * from "./offline.js";
 export * from "./execution/index.js";
-export { RemoteSkillsClient, createRemoteSkillsClient, RemoteRequestError, RemoteRouteUnsupportedError, RemoteCapabilityUnavailableError, RemoteWorkspaceMemberError } from "../lib/remote-client.js";
+export { RemoteSkillsClient, createRemoteSkillsClient, RemoteRequestError, RemoteRouteUnsupportedError, RemoteCapabilityUnavailableError, RemoteQuoteUnavailableError, RemoteWorkspaceMemberError } from "../lib/remote-client.js";
+export type { RemoteQuoteUnavailableCode } 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";
@@ -45,3 +46,5 @@ export { WorkspaceLeaveInputError, RemoteWorkspaceLeaveError, RemoteWorkspaceLea
 export type { RemoteWorkspaceInvitation, RemoteWorkspaceInvitationsPage, RemoteWorkspaceInvitationResult, RemoteWorkspaceInvitationAcceptance, ListRemoteWorkspaceInvitations, IssueRemoteWorkspaceInvitation, ResendRemoteWorkspaceInvitation, RevokeRemoteWorkspaceInvitation, AcceptRemoteWorkspaceInvitation, RemoteWorkspaceInvitationErrorCode } from "../lib/remote-invitations.js";
 export { WorkspaceInvitationInputError, RemoteWorkspaceInvitationError, RemoteWorkspaceInvitationUnconfirmedError, RemoteWorkspaceInvitationReadError } from "../lib/remote-invitations.js";
 export { InvitationEmailInputError, RemoteInvitationEmailError, RemoteInvitationEmailUnconfirmedError, type RequestInvitationEmailChallenge, type AcceptInvitationEmailChallenge, type RemoteInvitationEmailChallenge, type RemoteInvitationEmailAcceptance, type RemoteInvitationEmailErrorCode } from "../lib/remote-invitation-recovery.js";
+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";