@hasna/skills 0.4.0 → 0.5.1

package/dist/lib/remote-workspace-selection.d.ts

@@ -0,0 +1,58 @@
+import type { RemoteCurrentWorkspace, RemoteCustomerProfile, RemoteCustomerRole } from "./remote-profile.js";
+/** An observed identity and exact membership incarnation, never a slug or cached role. */
+export type RemoteWorkspaceContext = Readonly<{
+    userId: string;
+    membershipId: string;
+}>;
+export type RemoteAccountWorkspace = {
+    membershipId: string;
+    organization: RemoteCurrentWorkspace;
+    role: RemoteCustomerRole;
+    current: boolean;
+};
+export type RemoteAccountWorkspaces = {
+    workspaces: RemoteAccountWorkspace[];
+};
+export type RemoteWorkspaceIdentity = {
+    user: RemoteCustomerProfile & {
+        membershipId: string;
+    };
+    organization: RemoteCurrentWorkspace;
+};
+/** Contains a secret. SDK callers own its lifetime; never print or persist it implicitly. */
+export type RemoteWorkspaceSession = RemoteWorkspaceIdentity & {
+    token: string;
+};
+export type RemoteAccountWorkspaceDiscovery = RemoteAccountWorkspaces & {
+    userId: string;
+};
+export declare const invalidWorkspaceResult = "The server returned an invalid workspace selection result.";
+export declare class WorkspaceContextInputError extends Error {
+    constructor();
+}
+export declare class WorkspaceIdentityMismatchError extends Error {
+    constructor();
+}
+export declare function workspaceExpectedUserId(value: unknown): string;
+/** Copy before the first await: caller mutations cannot retarget verification. */
+export declare function workspaceContext(value: unknown): RemoteWorkspaceContext;
+/** Project documented fields only; server extras cannot reach display metadata. */
+export declare function parseAccountWorkspaces(value: unknown): RemoteAccountWorkspaces;
+export declare function parseWorkspaceIdentity(value: unknown, expectedUserId: string): RemoteWorkspaceIdentity;
+/** The service still verifies the token; response metadata never grants authority. */
+export declare function parseWorkspaceSession(value: unknown, expected: RemoteWorkspaceContext): RemoteWorkspaceSession;
+/** Fresh verification does not require newer workspace metadata from default-only servers. */
+export declare function parseWorkspaceLogin(value: unknown, expectedUserId?: string): {
+    token: string;
+    userId: string;
+};
+export declare const workspaceSelectionFailures: {
+    readonly INVALID_WORKSPACE_SELECTION: readonly [400, "Provide only the exact membership ID from your workspace list."];
+    readonly SESSION_EXPIRED: readonly [401, "Sign in again before selecting a workspace."];
+    readonly ACCOUNT_UNAVAILABLE: readonly [403, "Account is unavailable."];
+    readonly INTERACTIVE_SESSION_REQUIRED: readonly [403, "Interactive sign-in is required to select a workspace."];
+    readonly WORKSPACE_UNAVAILABLE: readonly [404, "Workspace is unavailable. Refresh your workspace list."];
+    readonly WORKSPACE_BUSY: readonly [503, "Workspace is busy. Refresh before retrying."];
+};
+export type RemoteWorkspaceSelectionErrorCode = keyof typeof workspaceSelectionFailures;
+export declare function workspaceSelectionFailure(value: unknown, status: number): RemoteWorkspaceSelectionErrorCode | null;

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

@@ -0,0 +1,76 @@
+import type { RemoteCustomerRole } from "./remote-profile.js";
+export type RemoteWorkspaceMember = {
+    membershipId: string;
+    userId: string;
+    email: string;
+    displayName: string | null;
+    role: RemoteCustomerRole;
+    /** Exact server timestamp, including microseconds; never rounded to Date. */
+    createdAt: string;
+};
+export type RemoteWorkspaceMembersPage = {
+    organizationId: string;
+    members: RemoteWorkspaceMember[];
+    nextCursor: string | null;
+};
+export type RemoteWorkspaceMembersOptions = {
+    limit?: number;
+    cursor?: string;
+};
+export type SetRemoteWorkspaceMemberRole = {
+    role: RemoteCustomerRole;
+    expectedRole: RemoteCustomerRole;
+};
+export type RemoveRemoteWorkspaceMember = {
+    expectedRole: RemoteCustomerRole;
+};
+export type RemoteWorkspaceMemberRoleResult = {
+    organizationId: string;
+    member: RemoteWorkspaceMember;
+    changed: boolean;
+};
+export type RemoteWorkspaceMemberRemovalResult = {
+    organizationId: string;
+    membershipId: string;
+    removed: true;
+    alreadyRemoved: boolean;
+};
+/** Pagination is transport input, not a workspace or authority selector. */
+export declare function workspaceMembersQuery(options?: RemoteWorkspaceMembersOptions): string;
+export declare class WorkspaceMemberInputError extends Error {
+    constructor();
+}
+/** Snapshot transport input before verification awaits; authority stays on the server. */
+export declare function workspaceMemberRoleInput(membershipId: string, input: SetRemoteWorkspaceMemberRole): {
+    membershipId: string;
+    body: {
+        role: RemoteCustomerRole;
+        expectedRole: RemoteCustomerRole;
+    };
+};
+export declare function workspaceMemberRemovalInput(membershipId: string, input: RemoveRemoteWorkspaceMember): {
+    membershipId: string;
+    body: {
+        expectedRole: RemoteCustomerRole;
+    };
+};
+export declare const invalidMemberResult = "The server returned an invalid workspace member result. Refresh the roster before another action.";
+export declare function parseWorkspaceMemberRoleResult(value: unknown, membershipId: string, role: RemoteCustomerRole): RemoteWorkspaceMemberRoleResult;
+export declare function parseWorkspaceMemberRemovalResult(value: unknown, membershipId: string): RemoteWorkspaceMemberRemovalResult;
+/** Only known code/status pairs become public messages; arbitrary server text stays private. */
+export declare const workspaceMemberFailures: {
+    readonly INVALID_REQUEST: readonly [400, "Provide the exact membership role parameters."];
+    readonly ACCOUNT_UNAVAILABLE: readonly [403, "Account is unavailable."];
+    readonly INTERACTIVE_SESSION_REQUIRED: readonly [403, "Fresh interactive sign-in is required."];
+    readonly WORKSPACE_ADMIN_REQUIRED: readonly [403, "A current workspace owner or admin is required."];
+    readonly MEMBERSHIP_ACTION_FORBIDDEN: readonly [403, "Your current workspace role cannot perform this membership action."];
+    readonly MEMBERSHIP_NOT_FOUND: readonly [404, "Membership was not found in the current workspace."];
+    readonly SELF_REMOVAL_UNAVAILABLE: readonly [409, "Leaving your own workspace is not available through member removal."];
+    readonly MEMBERSHIP_ROLE_CHANGED: readonly [409, "The member role changed. Refresh the roster before another action."];
+    readonly LAST_OWNER_REQUIRED: readonly [409, "The workspace must retain at least one active owner."];
+    readonly MEMBERSHIP_BUSY: readonly [503, "Membership is busy. Refresh the roster before another action."];
+};
+export type RemoteWorkspaceMemberErrorCode = keyof typeof workspaceMemberFailures;
+export declare function workspaceMemberFailure(value: unknown, status: number): RemoteWorkspaceMemberErrorCode | null;
+/** Project the documented roster only; auth metadata and other fields stay out. */
+export declare function parseWorkspaceMembersPage(value: unknown): RemoteWorkspaceMembersPage;

package/dist/lib/skillinfo.d.ts

@@ -45,7 +45,7 @@ export declare function getSkillDependencyStatus(name: string): SkillDependencyS
  */
 export declare function runSkill(name: string, args: string[], options?: {
     installed?: boolean;
-    stdio?: "inherit" | "pipe";
+    stdio?: "inherit" | "pipe" | "stderr";
     env?: Record<string, string>;
 }): Promise<{
     exitCode: number;

package/dist/lib/workspace-profile.d.ts

@@ -0,0 +1,49 @@
+type Env = Record<string, string | undefined>;
+export declare class WorkspaceProfileError extends Error {
+}
+/** Capture actual key authority before OTP; cached identity never supplies authority. */
+export declare function prepareProfileWorkspace(action: string, source?: Env): {
+    origin: string;
+    resolve(): Promise<{
+        origin: string;
+        context: undefined;
+        unchanged: () => void;
+    } | {
+        origin: string;
+        context: Readonly<{
+            userId: string;
+            membershipId: string;
+        }>;
+        unchanged: () => void;
+    }>;
+};
+export declare function captureProfileWorkspace(action: string, source?: Env): Promise<{
+    origin: string;
+    context: undefined;
+    unchanged: () => void;
+} | {
+    origin: string;
+    context: Readonly<{
+        userId: string;
+        membershipId: string;
+    }>;
+    unchanged: () => void;
+}>;
+/** Own only the explicitly named profile; injected credentials may not hide enrollment. */
+export declare function prepareWorkspaceEnrollment(membershipId: string, source?: Env): Promise<{
+    profile: string;
+    origin: string;
+    complete(email: string, code: string): Promise<{
+        status: string;
+        profile: string;
+        apiUrl: string;
+        userId: string;
+        email: string;
+        membershipId: string;
+        organization: string;
+        organizationId: string;
+        role: import("./remote-profile.js").RemoteCustomerRole;
+        keyCreated: boolean;
+    }>;
+}>;
+export {};

package/dist/mcp/helpers.d.ts

@@ -1,3 +1,24 @@
+/** The shape every tool handler returns; kept structural so registrars need no SDK type import. */
+type McpToolResult = {
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    isError?: boolean;
+};
+/**
+ * Run a DATA tool behind the fleet ladder's refusal.
+ *
+ * The body is expected to go through `requireSkillsReadAccess()` /
+ * `getBrowseRegistry()` (lib/read-access.ts) before it reads the bundled
+ * catalog or the on-machine corpus. When the ladder refuses — no credential, no
+ * authority, no `HASNA_SKILLS_LOCAL=1` opt-in; an authority with no key; a
+ * deliberate selection that cannot be honoured — the refusal comes back as the
+ * same `AUTH_REQUIRED` result `get_run_status` already gives, never as the
+ * local answer. Any other failure propagates unchanged (the SDK reports it as
+ * a tool error with its message).
+ */
+export declare function readSurface(body: () => Promise<McpToolResult>): Promise<McpToolResult>;
 export declare function stripNulls(obj: Record<string, unknown>): Record<string, unknown>;
 export declare function cacheGet(key: string): unknown | undefined;
 export declare function cacheSet(key: string, value: unknown): void;
@@ -24,3 +45,4 @@ export declare const TOOL_DESCRIPTIONS: Record<string, {
     description: string;
     params: string[];
 }>;
+export {};

package/dist/mcp/index.d.ts

@@ -8,6 +8,22 @@
  *   skills-mcp          # Direct binary
  *   skills-mcp --http   # Streamable HTTP on 127.0.0.1:8836
  */
+/**
+ * FAIL CLOSED AT STARTUP (owner ruling 2026-09-04, hasna/apps#1720; #1720
+ * validation, round 1): the MCP process resolves the fleet ladder BEFORE it
+ * connects any transport. With no credential, no authority and no
+ * `HASNA_SKILLS_LOCAL=1` opt-in it exits 1 with the ladder's one line on
+ * stderr — before `initialize` is answered, before an HTTP port is bound —
+ * mirroring the CLI, which exits 1 on the same machine. Serving the bundled
+ * catalog to an agent host that registered `skills-mcp` on a station without
+ * its credential is the false green the ruling removed. The explicit local
+ * opt-in starts the server and announces local mode once on stderr; a
+ * credential (or a vault pointer the tools complete per call) starts it hosted.
+ *
+ * Every data tool still runs the same gate per call (lib/read-access.ts), so a
+ * credential that disappears mid-process is refused by the next call too.
+ */
+export declare function assertSkillsMcpConfigured(env?: Record<string, string | undefined>): void;
 /**
  * Start the Skills MCP server on stdio (newline-delimited JSON-RPC).
  *

package/dist/sdk/governance-store.d.ts

@@ -51,6 +51,7 @@ export interface GovernanceStore {
         estimatedCents: number;
     }): Promise<CreditReservation>;
     reservationsForRun(orgId: string, runId: string): Promise<CreditReservation[]>;
+    /** First terminal reconciliation wins; retries return that persisted state unchanged. */
     reconcileReservation(reservationId: string, actualCents: number, status: "charged" | "released"): Promise<CreditReservation | null>;
     /** Sum of cost_cents of runs created in the given calendar month (YYYY-MM), plus un-reconciled reservations. */
     monthlySpendCents(orgId: string, monthPrefix: string): Promise<number>;

package/dist/sdk/index.d.ts

@@ -15,7 +15,7 @@
  * — the shared @hasna/contracts ladder — instead of reading an environment
  * variable of its own. See lib/fleet-credentials.ts.
  */
-export { MissingSkillsFleetError, SkillsFleetCredentialError, SKILLS_API_KEY_ENV, SKILLS_API_URL_ENV, SKILLS_APP, configuredSkillsApiUrl, noticeLocalSkillsMode, normalizeSkillsApiOrigin, requireSkillsApiOrigin, requireSkillsFleet, resolveSkillsApiOrigin, resolveSkillsFleet, skillsCredentialFilePath, skillsCredentialFiles, skillsCredentialOrReason, type HostedSkillsFleet, type LocalSkillsFleet, type SkillsFleet, type SkillsFleetErrorCode, type SkillsFleetOptions, } from "../lib/fleet-credentials.js";
+export { MissingSkillsFleetError, SkillsFleetCredentialError, SKILLS_API_KEY_ENV, SKILLS_API_URL_ENV, SKILLS_APP, SKILLS_LOCAL_OPT_IN_ENV_KEYS, configuredSkillsApiUrl, isSkillsLocalOptIn, noticeLocalSkillsMode, normalizeSkillsApiOrigin, requireSkillsApiOrigin, requireSkillsFleet, resolveSkillsApiOrigin, resolveSkillsFleet, selectsSkillsLocalMode, skillsCredentialFilePath, skillsCredentialFiles, skillsCredentialOrReason, type HostedSkillsFleet, type LocalSkillsFleet, type SkillsFleet, type SkillsFleetErrorCode, type SkillsFleetOptions, } from "../lib/fleet-credentials.js";
 export * from "./server.js";
 export * from "./registry.js";
 export * from "./runs.js";
@@ -30,7 +30,13 @@ 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 { RemoteSkillsClient, createRemoteSkillsClient, RemoteRequestError, RemoteRouteUnsupportedError, RemoteCapabilityUnavailableError, RemoteWorkspaceMemberError } 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";
+export type { RemoteWorkspaceMember, RemoteWorkspaceMembersPage, RemoteWorkspaceMembersOptions } from "../lib/remote-workspace.js";
+export type { SetRemoteWorkspaceMemberRole, RemoveRemoteWorkspaceMember, RemoteWorkspaceMemberRoleResult, RemoteWorkspaceMemberRemovalResult, RemoteWorkspaceMemberErrorCode } from "../lib/remote-workspace.js";
+export type { RemoteCustomerRole, RemoteCustomerProfile, RemoteCurrentWorkspace, UpdateRemoteProfile, UpdateRemoteWorkspace } from "../lib/remote-profile.js";
+export type { RemoteWorkspaceContext, RemoteAccountWorkspace, RemoteAccountWorkspaces, RemoteWorkspaceIdentity, RemoteWorkspaceSession, RemoteAccountWorkspaceDiscovery, RemoteWorkspaceSelectionErrorCode } from "../lib/remote-workspace-selection.js";
+export { WorkspaceContextInputError, WorkspaceIdentityMismatchError } from "../lib/remote-workspace-selection.js";
+export { RemoteWorkspaceSelectionError } from "../lib/remote-client.js";