@hasna/skills 0.8.8 → 0.8.10

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

@@ -1,5 +1,6 @@
 export declare const INTEGRATION_AGENTS: readonly ["claude", "codex", "gemini", "opencode", "cursor", "hermes"];
 export type IntegrationAgent = typeof INTEGRATION_AGENTS[number];
+export declare function renderAgentHookCommand(command: string, agent: IntegrationAgent, profileId: string, event: string): string;
 export declare const AGENT_ADAPTERS: {
     readonly claude: {
         readonly root: ".claude/skills";

package/dist/lib/agent-codex-trust.d.ts

@@ -0,0 +1,42 @@
+import { connectCodexHookRpc } from "./codex-hook-rpc.js";
+import { type ReviewedSkillsCli } from "./codex-hook-trust-identity.js";
+export interface CodexNativeHookTrustOptions {
+    home?: string;
+    dataDir?: string;
+    codexCommand?: string;
+    apply?: boolean;
+    reviewedPlanDigest?: string;
+    reviewedSkillsCli?: ReviewedSkillsCli;
+}
+type Connect = typeof connectCodexHookRpc;
+/** Deliberately separate from filesystem hook installation: native trust is an
+ * explicit authorization of exact owned commands, never a broad trust bypass. */
+export declare function enrollCodexNativeHooks(options?: CodexNativeHookTrustOptions, connect?: Connect): Promise<{
+    planDigest: string;
+    skillsCli: {
+        path: string;
+        version: string;
+        sha256: string;
+        manifestSha256: string;
+    };
+    nativeVersion: string;
+    ownedNativeProcessId: number | undefined;
+    agent: string;
+    applied: boolean;
+    planned: {
+        key: any;
+        event: string;
+        command: string;
+        handlerType: any;
+        timeoutSec: any;
+        sourcePath: any;
+        currentHash: any;
+        enabled: any;
+        trustStatus: any;
+    }[];
+    nativeEligible: boolean;
+    transport: string;
+    existingSessionsReloaded: boolean;
+    nativeExecutionVerified: boolean;
+}>;
+export {};

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

@@ -0,0 +1,10 @@
+export declare const CODEX_SKILL_CONFIG_SECTIONS: RegExp;
+/** The path editor supports ordinary array-of-table sections only. Removing
+ * those sections must remove exactly the parsed path array, with all other
+ * values unchanged. This also excludes header-like text inside user strings. */
+export declare function assertCodexPathConfigEditable(text: string): void;
+/** Preserve user TOML verbatim except for the supported bundled-skill control.
+ * Bun's parser accepts some illegal table reopenings, so never append a table
+ * over an existing inline/dotted skills definition. Refuse unfamiliar layouts
+ * before the integration transaction writes any files. */
+export declare function disableCodexBundledSkills(text: string): string;

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

@@ -1,10 +1,12 @@
 import type { IntegrationAgent } from "./agent-adapters.js";
 import { type DiscoveryDirectory } from "./agent-discovery-directories.js";
+import { type ManagedPluginRegistrationWitness } from "./plugin-discovery.js";
 export { captureDiscoveryDirectories, type DiscoveryDirectory } from "./agent-discovery-directories.js";
 export interface DiscoverySource {
     path: string;
     sha256: string | null;
-    hashMode?: "bytes" | "path-bytes";
+    hashMode?: "bytes" | "path-bytes" | "claude-plugin-registry";
+    managedPlugins?: ManagedPluginRegistrationWitness[];
     format?: "json" | "toml" | "yaml";
     fields?: string[];
 }
@@ -35,7 +37,7 @@ export declare function captureDiscoveryPathSources(paths: string[]): DiscoveryS
 /** Project settings can introduce a higher-precedence discovery source. Until
  * its native merge format is supported, refuse that layer rather than certify
  * the home-only inventory. Ordinary unrelated project settings remain usable. */
-export declare function assertProjectDiscovery(agent: IntegrationAgent, directories: string[], home: string, canonical?: (path: string) => string): void;
+export declare function assertProjectDiscovery(agent: IntegrationAgent, directories: string[], home: string, canonical?: (path: string) => string, reviewed?: AgentDiscoveryBinding): void;
 /** Resolve configured plugin discovery without starting an agent or loading a plugin.
  * Unknown runtime registrations require explicit reviewed inputs, never a cache guess. */
 export declare function resolveAgentDiscovery(options: {

package/dist/lib/codex-hook-rpc.d.ts

@@ -0,0 +1,13 @@
+export declare const SUPPORTED_CODEX_HOOK_VERSIONS: readonly ["codex-cli 0.153.0", "codex-cli 0.154.0", "codex-cli 0.155.0"];
+export interface CodexHookRpc {
+    version: string;
+    processId?: number;
+    request(method: string, params: unknown): Promise<any>;
+    close(): Promise<void>;
+}
+/** An owned, short-lived native client. It cannot reload other app servers. */
+export declare function connectCodexHookRpc(options: {
+    command: string;
+    home: string;
+    codexHome: string;
+}): Promise<CodexHookRpc>;

package/dist/lib/codex-hook-trust-files.d.ts

@@ -0,0 +1,15 @@
+import { type BigIntStats } from "node:fs";
+export declare function need(value: unknown, code: string): asserts value;
+export declare function snapshot(file: string, privateFile?: boolean, options?: {
+    readOnlyPackage?: true;
+}): {
+    file: string;
+    privateFile: boolean;
+    readOnlyPackage: boolean;
+    text: string;
+    bytes: Buffer<ArrayBuffer>;
+    stat: BigIntStats;
+    sha256: string;
+};
+export declare function unchanged(before: ReturnType<typeof snapshot>): void;
+export declare function save(file: string, content: string | Buffer): void;

package/dist/lib/codex-hook-trust-identity.d.ts

@@ -0,0 +1,16 @@
+/** A private release adapter supplies a reviewed registry artifact identity;
+ * the normal CLI binds to its own installed entrypoint instead. */
+export interface ReviewedSkillsCli {
+    path: string;
+    version: string;
+    sha256: string;
+}
+export declare function bindSkillsCli(command: string, reviewed?: ReviewedSkillsCli): {
+    receipt: {
+        path: string;
+        version: string;
+        sha256: string;
+        manifestSha256: string;
+    };
+    recheck(): void;
+};

package/dist/lib/codex-hook-trust-layout.d.ts

@@ -0,0 +1,3 @@
+/** Conservative admission and text witness, never a TOML writer. Native Codex
+ * performs the versioned write; unrecognized inline/dotted trust shapes refuse. */
+export declare function codexTrustTextWitness(text: string, keys: string[]): string;

package/dist/lib/plugin-admission.d.ts

@@ -0,0 +1,101 @@
+import { type ProfileClient } from "./profile-client.js";
+import { type SelectionCacheOptions } from "./selection-cache.js";
+import { type PluginFileWitness, type PluginProjectionManifest } from "./plugin-projection.js";
+import type { ResolvedSkillSelection } from "../types/skill-selection.js";
+/** Version 1 is certified against native Claude 2.1.274 and 2.1.276; new hosts require a contract revision/test. */
+export interface PluginAdmissionTarget {
+    schemaVersion: 1;
+    pluginId: string;
+    /** One marketplace command serves all explicitly reviewed native registration scopes. */
+    registrations: Array<{
+        scope: "user" | "project";
+        projectPath: string | null;
+    }>;
+    native: {
+        version: "2.1.274" | "2.1.276";
+        executable: string;
+        digest: string;
+    };
+    resolver: {
+        executable: string;
+        digest: string;
+    };
+}
+export interface PluginAdmissionBinding {
+    schemaVersion: 2;
+    authority: string;
+    workspaceId: string;
+    /** Stable account subject. Raw credential/key identities are never persisted. */
+    principal: PluginAdmissionPrincipal;
+    profileId: string;
+    bundleSlug: string;
+    target: PluginAdmissionTarget;
+}
+export type PluginBundleIdentity = Pick<ResolvedSkillSelection, "slug" | "version" | "bundleDigest">;
+export interface PluginAdmissionPrincipal {
+    userId: string;
+    accountId: string;
+    role: "owner";
+}
+export interface PluginRoutingIdentity extends PluginBundleIdentity {
+    aliases?: string[];
+    triggers?: {
+        keywords?: string[];
+        paths?: string[];
+        always?: boolean;
+    };
+}
+/** Every field that can route or activate the admitted plugin participates in approval. */
+export interface PluginAdmissionIdentity {
+    schemaVersion: 3;
+    binding: PluginAdmissionBinding;
+    bindingId: string;
+    profileRevision: string;
+    selection: PluginRoutingIdentity;
+    payloadSelections: PluginRoutingIdentity[];
+    manifest: PluginProjectionManifest;
+    originalTreeDigest: string;
+    projectionTreeDigest: string;
+    files: PluginFileWitness[];
+    removed: PluginFileWitness[];
+    sourceCommand: string;
+    /** Approved digest of the authenticated routing evidence snapshot. */
+    evidenceDigest: string;
+}
+export interface PluginAdmissionPlan extends PluginAdmissionIdentity {
+    observation: {
+        principal: PluginAdmissionPrincipal;
+        profileRevision: string;
+        integration: PluginRoutingIdentity;
+        payloads: PluginRoutingIdentity[];
+    };
+    planDigest: string;
+}
+export interface PluginAdmissionReceipt {
+    schemaVersion: 3;
+    plan: PluginAdmissionPlan;
+    materializedPath: string;
+    admittedAt: string;
+}
+/** Client/store injections are for embedding and isolated tests. The CLI exposes neither. */
+export interface PluginAdmissionOptions extends Pick<SelectionCacheOptions, "now"> {
+    client?: ProfileClient;
+    storeRoot?: string;
+    timeoutMs?: number;
+}
+export declare function pluginAdmissionRoot(): string;
+export declare function validatePluginTarget(value: unknown): asserts value is PluginAdmissionTarget;
+/** The accepted native command opens and hashes one inode, then executes that same descriptor. */
+export declare function pluginResolverCommand(binding: PluginAdmissionBinding): string;
+export declare function pluginBindingPath(storeRoot: string, id: string): string;
+export declare function pluginReceiptPath(storeRoot: string, id: string, digest: string): string;
+export declare function readPluginBinding(storeRoot: string, id: string): PluginAdmissionBinding;
+export declare function readPluginAdmissionReceipt(storeRoot: string, id: string, digest: string): PluginAdmissionReceipt;
+/** Command sources inherit an untrusted shell environment; authority comes from normal owner credentials. */
+export declare function assertPluginAuthorityEnvironment(env?: Record<string, string | undefined>): void;
+/** API reads only: a plan neither writes caches nor admits or executes package code. */
+export declare function planPluginAdmission(spec: string, profileId: string, target: PluginAdmissionTarget, options?: PluginAdmissionOptions): Promise<PluginAdmissionPlan>;
+/** Explicit local admission. Original archive and migrated payloads are already privately published. */
+export declare function admitPlugin(spec: string, profileId: string, target: PluginAdmissionTarget, approvedDigest: string, approvedEvidenceDigest: string, options?: PluginAdmissionOptions): Promise<PluginAdmissionReceipt>;
+/** Fresh authority on every invocation. No receipt, API failure or revocation ever returns a stale directory. */
+export declare function resolveAdmittedPlugin(id: string, options?: PluginAdmissionOptions): Promise<string>;

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

@@ -0,0 +1,13 @@
+export interface ManagedPluginRegistrationWitness {
+    bindingId: string;
+    storeRoot: string;
+}
+export declare function validateManagedPluginWitnesses(value: unknown): asserts value is ManagedPluginRegistrationWitness[];
+/** This is a structured witness, not an exemption for a plugin ID or its cache directory. */
+export declare function hashManagedPluginRegistry(path: string, managed: ManagedPluginRegistrationWitness[]): string;
+export declare function captureManagedPluginRegistry(path: string, managedPlugins: ManagedPluginRegistrationWitness[]): {
+    path: string;
+    hashMode: "claude-plugin-registry";
+    managedPlugins: ManagedPluginRegistrationWitness[];
+    sha256: string;
+};

package/dist/lib/plugin-projection-store.d.ts

@@ -0,0 +1,14 @@
+import type { SkillBundleEntry } from "./skill-bundle.js";
+import { type PluginFileWitness } from "./plugin-projection.js";
+/** Snapshot every file, rejecting empty directories and any membership or metadata change. */
+export declare function snapshotPluginTree(root: string, options?: {
+    nativeRuntime?: "claude-2.1.274" | "claude-2.1.276";
+}): SkillBundleEntry[];
+export declare function verifyPluginTree(root: string, witnesses: PluginFileWitness[]): void;
+/** Sibling staging and an exclusive, nonwaiting lock serialize cooperative publishers. */
+export declare function materializePluginTree(root: string, entries: SkillBundleEntry[]): void;
+export declare function readPluginJson(path: string): unknown | null;
+/** Atomic link publication never overwrites an existing receipt. */
+export declare function writePluginJsonImmutable(path: string, value: unknown): void;
+/** Hash the reviewed executable without executing it or allocating the entire binary. */
+export declare function pluginExecutableDigest(path: string): string;

package/dist/lib/plugin-projection.d.ts

@@ -0,0 +1,80 @@
+import type { SkillBundleEntry } from "./skill-bundle.js";
+import type { SkillSelection } from "../types/skill-selection.js";
+export declare const PLUGIN_PROJECTION_MANIFEST = "plugin-projection.json";
+export declare const PLUGIN_PROJECTION_LIMITS: Readonly<{
+    files: 1024;
+    bytes: number;
+    fileBytes: number;
+    metadataBytes: number;
+    registrations: 64;
+    history: 128;
+}>;
+export interface PluginPayloadMapping {
+    path: string;
+    kind: "skill" | "command";
+    /** Digest of the original one-file tree, including its path and mode. */
+    sourceDigest: string;
+    target: Pick<SkillSelection, "slug" | "version" | "bundleDigest">;
+}
+interface PluginProjectionFields {
+    agent: "claude";
+    pluginId: string;
+    payloads: PluginPayloadMapping[];
+}
+interface PluginUpstream {
+    source: string;
+    revision: string;
+    license: string;
+    treeDigest: string;
+}
+interface PluginReview {
+    hooks: "reviewed-no-skill-injection";
+    dependencies: "reviewed-no-retired-payload-dependency";
+}
+export type PluginProjectionManifest = PluginProjectionFields & ({
+    schemaVersion: 1;
+    upstream: PluginUpstream & {
+        version: string;
+    };
+    review: PluginReview;
+} | {
+    schemaVersion: 2;
+    upstream: PluginUpstream & {
+        version: string | null;
+    };
+    review: PluginReview & {
+        documentation: Array<{
+            path: string;
+            sourceDigest: string;
+        }>;
+    };
+});
+export interface PluginFileWitness {
+    path: string;
+    mode: number;
+    size: number;
+    sha256: string;
+}
+export interface PluginProjection {
+    manifest: PluginProjectionManifest;
+    payloads: PluginPayloadMapping[];
+    files: SkillBundleEntry[];
+    witnesses: PluginFileWitness[];
+    originalTreeDigest: string;
+    projectionTreeDigest: string;
+    removed: PluginFileWitness[];
+}
+export declare function pluginRefusal(message: string): never;
+export declare function pluginNeed(value: unknown, message: string): asserts value;
+export declare const pluginHash: (bytes: string | Uint8Array) => string;
+export declare function pluginObject(value: unknown): value is Record<string, unknown>;
+export declare function pluginKeys(value: unknown, keys: string[]): asserts value is Record<string, unknown>;
+export declare function pluginText(value: unknown, limit?: number): asserts value is string;
+export declare function pluginId(value: unknown): asserts value is string;
+export declare function pluginDigest(value: unknown): asserts value is string;
+export declare function validatePluginManifest(value: unknown): asserts value is PluginProjectionManifest;
+export declare function pluginFileWitnesses(entries: SkillBundleEntry[]): PluginFileWitness[];
+export declare function pluginTreeDigest(entries: SkillBundleEntry[]): string;
+/** Pure projection: no filesystem access, upstream commands, package installation or publication. */
+export declare function buildPluginProjection(entries: SkillBundleEntry[]): PluginProjection;
+export {};

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

@@ -1,18 +1,28 @@
 import type { ResolvedSkillProfile, StationSkillState, StationSkillStateInput } from "../types/skill-selection.js";
 export interface ProfileClient {
     readonly authority: string;
+    /** Stable whoami subject; raw credential/key identities are intentionally excluded. */
+    resolvePrincipal?(): Promise<AuthenticatedProfilePrincipal>;
     resolveProfile(id: string): Promise<ResolvedSkillProfile>;
     recordStation(id: string, state: StationSkillStateInput): Promise<StationSkillState>;
     getBundle(slug: string, version: string): Promise<Response | null>;
 }
+export type AuthenticatedProfileRole = "owner" | "admin" | "member" | "viewer";
+export interface AuthenticatedProfilePrincipal {
+    userId: string;
+    accountId: string;
+    role: AuthenticatedProfileRole;
+}
 export declare class HttpProfileClient implements ProfileClient {
     private key;
     readonly authority: string;
     private origin;
     constructor(key: string, origin: string);
+    private requestRoute;
     private request;
     private read;
     resolveProfile(id: string): Promise<ResolvedSkillProfile>;
+    resolvePrincipal(): Promise<AuthenticatedProfilePrincipal>;
     recordStation(id: string, input: StationSkillStateInput): Promise<StationSkillState>;
     getBundle(slug: string, version: string): Promise<Response | null>;
 }

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

@@ -9,6 +9,7 @@ import { type RemoteCreditPack, type RemoteRunApproval, type RemoteRunQuote } fr
 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";
+import { type RemoteSkillsAccess } from "./remote-permissions.js";
 export type { RemoteQuoteUnavailableCode } from "./remote-quote-errors.js";
 /**
  * A server that predates this client's pin/tag/incremental-sync routes answered
@@ -123,7 +124,9 @@ 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[], files?: RemoteInputFileDescriptor[]): Promise<RemoteRunQuote>;
-    getCapabilities(): Promise<{
+    getCapabilities(options?: {
+        refresh?: boolean;
+    }): Promise<RemoteSkillsAccess & {
         contractVersion: 1;
         apiVersion: 1;
         capabilities: string[];

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

@@ -11,7 +11,7 @@ export declare const REMOTE_CUSTOMER_OPERATIONS: readonly [{
     readonly title: "Get Server Capabilities";
     readonly parameter: null;
     readonly mutates: false;
-    readonly invoke: (client: RemoteSkillsClient) => Promise<{
+    readonly invoke: (client: RemoteSkillsClient) => Promise<import("./remote-permissions.js").RemoteSkillsAccess & {
         contractVersion: 1;
         apiVersion: 1;
         capabilities: string[];

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

@@ -0,0 +1,24 @@
+/** Effective access belongs to the credential, independently of workspace role. */
+export interface RemoteSkillsPermissions {
+    read?: boolean;
+    publish?: boolean;
+    profilesWrite?: boolean;
+    stationStateWrite?: boolean;
+    cloudSubmit?: boolean;
+    executionGrantsRead?: boolean;
+    executionGrantsWrite?: boolean;
+    executionGrantsResolve?: boolean;
+}
+export interface RemoteSkillsAccess {
+    scopes?: string[];
+    permissions?: RemoteSkillsPermissions;
+}
+/** Pick known fields only; never reflect additive provider fields into diagnostics. */
+export declare function parseSkillsAccess(value: unknown): RemoteSkillsAccess;
+export declare class RemoteSkillsPermissionError extends Error {
+    readonly permission: "publish" | "profilesWrite";
+    readonly code = "SKILLS_PERMISSION_DENIED";
+    readonly status = 403;
+    constructor(permission: "publish" | "profilesWrite");
+}
+export declare function assertSkillsPermission(access: RemoteSkillsAccess, permission: "publish" | "profilesWrite"): void;

package/dist/lib/skill-doc-file.d.ts

@@ -0,0 +1,9 @@
+import type { SkillDocs } from "./skillinfo.js";
+export declare class SkillDocFileError extends Error {
+    readonly code: "SKILL_DOC_FILE_INVALID" | "SKILL_DOC_FILE_MISSING";
+    constructor(code: "SKILL_DOC_FILE_INVALID" | "SKILL_DOC_FILE_MISSING", message: string);
+}
+/** The docs command's aliases are not arbitrary bundle paths (skills load supports those). */
+export declare function resolveSkillDocFile(file?: string): "SKILL.md" | "README.md" | "CLAUDE.md" | undefined;
+/** Fall back only when no file was requested, identically for text, JSON and SDK reads. */
+export declare function selectSkillDoc(docs: SkillDocs, file?: string): string | null;

package/dist/lib/skillinfo.d.ts

@@ -15,9 +15,10 @@ export interface SkillRequirements {
  */
 export declare function getSkillDocs(name: string): SkillDocs | null;
 /**
- * Get the best available documentation for a skill (SKILL.md > README.md > CLAUDE.md)
+ * Get preferred documentation, or an exact docs alias (skill, readme, claude).
+ * Unknown aliases and missing explicitly requested files refuse without fallback.
  */
-export declare function getSkillBestDoc(name: string): string | null;
+export declare function getSkillBestDoc(name: string, file?: string): string | null;
 /**
  * Extract requirements from a skill's source files
  */

package/dist/sdk/index.d.ts

@@ -17,7 +17,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 } from "../lib/profile-client.js";
+export { HttpProfileClient, createProfileClient, type ProfileClient, type AuthenticatedProfilePrincipal, type AuthenticatedProfileRole } from "../lib/profile-client.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";
@@ -37,6 +37,7 @@ 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 { 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";
 export type { RecurringCapability, RecurringListOptions, RemoteRecurringErrorCode } from "../lib/remote-recurring.js";