@hasna/skills 0.7.3 → 0.8.1

package/dist/lib/remote-recurring-contract.d.ts

@@ -0,0 +1,165 @@
+import { z } from "zod/v4";
+/** Portable versioned wire values only. Eligibility, repricing, freshness, budgets
+ * and execution authority are verified by the configured server. */
+export declare const RECURRING_CONTRACT_VERSION: 1;
+export declare const MAX_RECURRING_CREDITS = 2147483647;
+export declare const recurringRequestSchema: z.ZodObject<{
+    contractVersion: z.ZodLiteral<1>;
+    skill: z.ZodString;
+    input: z.ZodRecord<z.ZodString, z.ZodJSONSchema>;
+    args: z.ZodArray<z.ZodString>;
+    runtime: z.ZodObject<{
+        timeoutMs: z.ZodNumber;
+        maxOutputBytes: z.ZodNumber;
+        maxAttempts: z.ZodNumber;
+        connectorOperations: z.ZodArray<z.ZodObject<{
+            connectorSlug: z.ZodString;
+            operationName: z.ZodString;
+        }, z.core.$strict>>;
+    }, z.core.$strict>;
+    everyMinutes: z.ZodNumber;
+    startsAt: z.ZodString;
+    expiresAt: z.ZodString;
+    dispatchGraceSeconds: z.ZodNumber;
+    period: z.ZodLiteral<"utc-day">;
+    inFlightPolicy: z.ZodLiteral<"finish-authorized-attempt">;
+    maxCreditsPerRun: z.ZodNumber;
+    maxCreditsPerPeriod: z.ZodNumber;
+    maxCreditsTotal: z.ZodNumber;
+    maxOccurrencesPerPeriod: z.ZodNumber;
+    maxOccurrencesTotal: z.ZodNumber;
+}, z.core.$strict>;
+export type RecurringRequest = z.infer<typeof recurringRequestSchema>;
+export interface RecurringTerms extends RecurringRequest {
+    deploymentId: string;
+    organizationId: string;
+    approvedByUserId: string;
+    approvedMembershipId: string;
+    policyId: string;
+    policyRevision: number;
+    skillId: string;
+    skillVersionId: string;
+    runtimeApprovalDigest: string;
+    payloadSha256: string;
+}
+export declare const recurringTermsSchema: z.ZodObject<{
+    contractVersion: z.ZodLiteral<1>;
+    skill: z.ZodString;
+    input: z.ZodRecord<z.ZodString, z.ZodJSONSchema>;
+    args: z.ZodArray<z.ZodString>;
+    runtime: z.ZodObject<{
+        timeoutMs: z.ZodNumber;
+        maxOutputBytes: z.ZodNumber;
+        maxAttempts: z.ZodNumber;
+        connectorOperations: z.ZodArray<z.ZodObject<{
+            connectorSlug: z.ZodString;
+            operationName: z.ZodString;
+        }, z.core.$strict>>;
+    }, z.core.$strict>;
+    everyMinutes: z.ZodNumber;
+    startsAt: z.ZodString;
+    expiresAt: z.ZodString;
+    dispatchGraceSeconds: z.ZodNumber;
+    period: z.ZodLiteral<"utc-day">;
+    inFlightPolicy: z.ZodLiteral<"finish-authorized-attempt">;
+    maxCreditsPerRun: z.ZodNumber;
+    maxCreditsPerPeriod: z.ZodNumber;
+    maxCreditsTotal: z.ZodNumber;
+    maxOccurrencesPerPeriod: z.ZodNumber;
+    maxOccurrencesTotal: z.ZodNumber;
+    deploymentId: z.ZodString;
+    organizationId: z.ZodUUID;
+    approvedByUserId: z.ZodUUID;
+    approvedMembershipId: z.ZodUUID;
+    policyId: z.ZodUUID;
+    policyRevision: z.ZodNumber;
+    skillId: z.ZodUUID;
+    skillVersionId: z.ZodUUID;
+    runtimeApprovalDigest: z.ZodString;
+    payloadSha256: z.ZodString;
+}, z.core.$strict>;
+export interface RecurringQuote {
+    costCredits: number;
+    quotedAt: string;
+    /** Quote is informational: admission always reprices under authority locks. */
+    admissionReprices: true;
+}
+export interface RecurringPreview {
+    contractVersion: typeof RECURRING_CONTRACT_VERSION;
+    draftId: string;
+    terms: RecurringTerms;
+    termsSha256: string;
+    quote: RecurringQuote;
+    approvalDeadline: string;
+    firstDueInstants: string[];
+    firstPeriod: {
+        startsAt: string;
+        endsAt: string;
+    };
+    additionalBudget: true;
+}
+export declare const recurringActivationSchema: z.ZodObject<{
+    contractVersion: z.ZodLiteral<1>;
+    acceptedTermsSha256: z.ZodString;
+    acceptance: z.ZodLiteral<"authorize-recurring-credit-use">;
+    idempotencyKey: z.ZodString;
+}, z.core.$strict>;
+export type RecurringActivation = z.infer<typeof recurringActivationSchema>;
+export interface RecurringBudget {
+    reservedCredits: number;
+    settledCredits: number;
+    admittedOccurrences: number;
+}
+export interface RecurringConsentView {
+    contractVersion: typeof RECURRING_CONTRACT_VERSION;
+    consentId: string;
+    scheduleId: string;
+    terms: RecurringTerms;
+    termsSha256: string;
+    state: "active" | "revoked" | "expired";
+    activatedAt: string;
+    revokedAt: string | null;
+    total: RecurringBudget;
+    currentPeriod: (RecurringBudget & {
+        startsAt: string;
+        endsAt: string;
+    }) | null;
+    nextDueAt: string | null;
+}
+export interface RecurringActivationResult {
+    replayed: boolean;
+    consent: RecurringConsentView;
+}
+export interface RecurringPage<T> {
+    contractVersion: typeof RECURRING_CONTRACT_VERSION;
+    items: T[];
+    nextCursor: string | null;
+}
+export type RecurringRefusal = "consent-inactive" | "authority-revoked" | "policy-disabled" | "policy-changed" | "skill-changed" | "quote-unavailable" | "per-run-ceiling" | "period-ceiling" | "total-ceiling" | "period-count" | "total-count" | "insufficient-credits" | "input-quota" | "runtime-unavailable";
+export interface RecurringOccurrenceView {
+    occurrenceId: string;
+    scheduleId: string;
+    dueAt: string;
+    periodStartsAt: string;
+    periodEndsAt: string;
+    outcome: "admitted" | "skipped" | "refused";
+    reason: RecurringRefusal | "dispatch-grace-elapsed" | null;
+    runId: string | null;
+    quotedCredits: number | null;
+    allocationState: "reserved" | "captured" | "released" | null;
+}
+export interface RecurringRevocation {
+    contractVersion: typeof RECURRING_CONTRACT_VERSION;
+    consentId: string;
+    revokedAt: string;
+    /** Bounded snapshot; separate paginated occurrences contains every run. */
+    authorizedRuns: {
+        runId: string;
+        attempt: number;
+        reservedCredits: number;
+    }[];
+    authorizedRunCount: number;
+    residualReservedCredits: number;
+    inFlightPolicy: "finish-authorized-attempt";
+    cancellationIsSeparate: true;
+}

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

@@ -0,0 +1,95 @@
+import { type RecurringRequest, type RecurringActivation, type RecurringPreview, type RecurringConsentView, type RecurringActivationResult, type RecurringPage, type RecurringOccurrenceView, type RecurringRevocation } from "./remote-recurring-contract.js";
+import type { RemoteWorkspaceIdentity } from "./remote-workspace-selection.js";
+export * from "./remote-recurring-contract.js";
+export interface RecurringCapability {
+    contractVersion: 1;
+    available: boolean;
+}
+export type RecurringListOptions = Readonly<{
+    limit?: number;
+    cursor?: string;
+}>;
+export type RecurringAction = "preview" | "draft" | "activate" | "list" | "get" | "occurrences" | "revoke";
+export type RecurringInputs = {
+    preview: RecurringRequest;
+    draft: {
+        draftId: string;
+    };
+    activate: {
+        draftId: string;
+        approval: RecurringActivation;
+    };
+    list: RecurringListOptions;
+    get: {
+        consentId: string;
+    };
+    occurrences: RecurringListOptions & {
+        consentId: string;
+    };
+    revoke: {
+        consentId: string;
+    };
+};
+export type RecurringResults = {
+    preview: RecurringPreview;
+    draft: RecurringPreview | null;
+    activate: RecurringActivationResult;
+    list: RecurringPage<RecurringConsentView>;
+    get: RecurringConsentView | null;
+    occurrences: RecurringPage<RecurringOccurrenceView>;
+    revoke: RecurringRevocation;
+};
+export declare class RecurringInputError extends Error {
+    readonly code = "RECURRING_INPUT_INVALID";
+    constructor();
+}
+export declare class RemoteRecurringUnavailableError extends Error {
+    readonly code = "RECURRING_UNAVAILABLE";
+    constructor();
+}
+export declare class RemoteRecurringReadError extends Error {
+    readonly code = "RECURRING_READ_FAILED";
+    constructor();
+}
+export declare class RemoteRecurringUnconfirmedError extends Error {
+    readonly code = "RECURRING_OUTCOME_UNKNOWN";
+    readonly outcomeUnknown = true;
+    constructor();
+}
+declare const failures: {
+    readonly RECURRING_INVALID_REQUEST: readonly [400, "Recurring parameters were refused."];
+    readonly RECURRING_INVALID_CURSOR: readonly [400, "Recurring page cursor was refused."];
+    readonly RECURRING_BODY_TOO_LARGE: readonly [413, "Recurring input exceeds the server limit."];
+    readonly RECURRING_UNAUTHENTICATED: readonly [401, "A current authenticated membership is required."];
+    readonly RECURRING_HUMAN_APPROVAL_REQUIRED: readonly [403, "A fresh human sign-in is required to activate recurring consent."];
+    readonly RECURRING_IMPERSONATION_DENIED: readonly [403, "Recurring changes are unavailable while impersonating."];
+    readonly RECURRING_AUTHORITY_REFUSED: readonly [403, "Current recurring authority was refused."];
+    readonly RECURRING_DEPLOYMENT_MISMATCH: readonly [403, "The recurring draft belongs to another deployment."];
+    readonly RECURRING_SKILL_CHANGED: readonly [409, "The recurring skill has changed."];
+    readonly RECURRING_TERMS_UNAVAILABLE: readonly [409, "The original recurring terms are unavailable."];
+    readonly RECURRING_QUOTE_EXCEEDS_CEILING: readonly [409, "The current quote exceeds the approved recurring ceiling."];
+    readonly RECURRING_NOT_FOUND: readonly [404, "Recurring state is unavailable for this account."];
+    readonly RECURRING_METHOD_NOT_ALLOWED: readonly [405, "The recurring operation is unsupported."];
+    readonly RECURRING_UNAVAILABLE: readonly [503, "Recurring operations are unavailable on this server."];
+    readonly INSUFFICIENT_SCOPE: readonly [403, "The credential lacks the required recurring scope."];
+    readonly RATE_LIMITED: readonly [429, "The recurring request limit was reached. Wait before another explicit request."];
+};
+export type RemoteRecurringErrorCode = keyof typeof failures;
+export declare class RemoteRecurringError extends Error {
+    readonly code: RemoteRecurringErrorCode;
+    readonly status: number;
+    constructor(code: RemoteRecurringErrorCode);
+}
+export declare function recurringFailure(value: unknown, status: number): RemoteRecurringErrorCode | null;
+/** Snapshot before any await. Validation does not substitute for server policy. */
+export declare function recurringInput<A extends RecurringAction>(action: A, raw: RecurringInputs[A]): RecurringInputs[A];
+export declare function parseRecurringCapability(value: unknown): RecurringCapability | undefined;
+export declare function assertRecurringCapability(value: unknown, action: RecurringAction): void;
+export declare function recurringRequest<A extends RecurringAction>(action: A, input: RecurringInputs[A]): {
+    path: string;
+    read: boolean;
+    method: string;
+    body: string | undefined;
+};
+/** Projects known response fields. Immutable terms remain exact and hash-bound. */
+export declare function parseRecurringResult<A extends RecurringAction>(action: A, value: unknown, input: RecurringInputs[A], identity: RemoteWorkspaceIdentity): RecurringResults[A];

package/dist/lib/skill-aliases.d.ts

@@ -1,6 +1,5 @@
-export declare const SKILL_ALIASES: {
-    readonly "create-blog-article": "blog-article";
-};
+/** @deprecated Aliases belong to an account's selected profile, never the package. */
+export declare const SKILL_ALIASES: Readonly<Record<string, string>>;
 export type SkillAlias = keyof typeof SKILL_ALIASES;
 export declare function normalizeSkillSlug(name: string): string;
 export declare function resolveSkillAlias(name: string): string;

package/dist/mcp/mcp-test-client.d.ts

@@ -1,5 +1,5 @@
-export declare const EXPECTED_ALL_SKILL_COUNT: number;
-export declare const EXPECTED_BASIC_SKILL_COUNT: 8;
+export declare const EXPECTED_ALL_SKILL_COUNT: 12;
+export declare const EXPECTED_BASIC_SKILL_COUNT: 12;
 /**
  * Helper class to communicate with the MCP server over stdio.
  */

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

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

package/dist/sdk/executor.d.ts

@@ -1,9 +1,9 @@
 /**
- * Executor seam: what actually runs a claimed skill run.
+ * Compatibility seam for historical unversioned run records.
  *
- * The interface is the contract an embedder supplies an executor against. The current
- * implementation is the provider-free deterministic handler the shipped worker runs
- * (src/server/handlers.ts) — same logs, same artifacts, same terminal transitions.
+ * Embedders may supply their own implementation of the interface. The legacy
+ * implementation only drains old records to a fenced refusal; versioned bundle
+ * execution uses the managed runtime and never resolves an embedded skill name.
  */
 import { ArtifactStorage } from "../server/artifact-storage.js";
 import { executeRun } from "../server/handlers.js";
@@ -12,6 +12,6 @@ import type { ServerRunRecord, SkillsProductStore } from "../server/types.js";
 export interface RunExecutor {
     execute(store: SkillsProductStore, run: ServerRunRecord, storage?: ArtifactStorage): Promise<ServerRunRecord>;
 }
-/** Current implementation: the shipped deterministic handler, unchanged. */
+/** @deprecated Drains legacy records with LEGACY_EXECUTION_RETIRED; executes no skill. */
 export declare const localRunExecutor: RunExecutor;
 export { executeRun };

package/dist/sdk/index.d.ts

@@ -33,6 +33,10 @@ 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 * from "../lib/remote-recurring-contract.js";
+export { RecurringInputError, RemoteRecurringError, RemoteRecurringUnavailableError, RemoteRecurringReadError, RemoteRecurringUnconfirmedError } from "../lib/remote-recurring.js";
+export type { RecurringCapability, RecurringListOptions, RemoteRecurringErrorCode } from "../lib/remote-recurring.js";
+export { canonicalJson, canonicalJsonSha256 } from "../lib/canonical-json.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";