@hasna/skills 0.6.3 → 0.7.1

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

@@ -0,0 +1,45 @@
+export declare const INTEGRATION_AGENTS: readonly ["claude", "codex", "gemini", "opencode", "cursor", "hermes"];
+export type IntegrationAgent = typeof INTEGRATION_AGENTS[number];
+export declare const AGENT_ADAPTERS: {
+    readonly claude: {
+        readonly root: ".claude/skills";
+        readonly config: ".claude/settings.json";
+        readonly events: readonly ["UserPromptSubmit", "SessionStart", "SubagentStart"];
+        readonly promptContext: true;
+    };
+    readonly codex: {
+        readonly root: ".codex/skills";
+        readonly config: ".codex/hooks.json";
+        readonly events: readonly ["UserPromptSubmit", "SessionStart", "SubagentStart"];
+        readonly promptContext: true;
+    };
+    readonly gemini: {
+        readonly root: ".gemini/skills";
+        readonly config: ".gemini/settings.json";
+        readonly events: readonly ["BeforeAgent", "SessionStart"];
+        readonly promptContext: true;
+    };
+    readonly opencode: {
+        readonly root: ".config/opencode/skills";
+        readonly config: ".config/opencode/opencode.json";
+        readonly events: readonly ["chat.message"];
+        readonly promptContext: true;
+    };
+    readonly hermes: {
+        readonly root: ".hermes/skills";
+        readonly config: ".hermes/config.yaml";
+        readonly events: readonly ["pre_llm_call", "pre_tool_call"];
+        readonly promptContext: true;
+        readonly promptFailureMode: "open";
+        readonly toolFailureMode: "supervised-child-errors-block";
+        readonly requiresNativeTrust: true;
+    };
+    readonly cursor: {
+        readonly root: ".cursor/skills";
+        readonly config: ".cursor/hooks.json";
+        readonly events: readonly ["beforeSubmitPrompt", "sessionStart"];
+        readonly promptContext: false;
+    };
+};
+export declare function normalizeAgentHookEvent(agent: IntegrationAgent, event: string): string;
+export declare function renderOpenCodePlugin(command: string, profileId: string): string;

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

@@ -0,0 +1,6 @@
+export declare const CLI_BRIDGE_NAME = "skills-cli";
+export declare const CLI_BRIDGE_VERSION = 1;
+export declare const CLI_BRIDGE_DIGEST: string;
+export declare const CLI_BRIDGE_FILES: Readonly<Record<string, string>>;
+/** Ownership is exact bytes at an expected location, never a marker's claim alone. */
+export declare function isOwnedCliBridge(path: string, expectedPaths: readonly string[]): boolean;

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

@@ -0,0 +1,37 @@
+import type { IntegrationAgent } from "./agent-adapters.js";
+export interface DiscoverySource {
+    path: string;
+    sha256: string | null;
+    format?: "json" | "toml" | "yaml";
+    fields?: string[];
+}
+export interface AgentDiscoveryBinding {
+    agent: IntegrationAgent;
+    roots: string[];
+    sources: DiscoverySource[];
+    method: "automatic" | "reviewed";
+    builtinNames?: string[];
+}
+export interface ReviewedDiscoveryInputs {
+    version: 1;
+    agents: Array<{
+        agent: IntegrationAgent;
+        roots: string[];
+        sources: DiscoverySource[];
+        pluginHooks: "reviewed-no-skill-injection";
+    }>;
+}
+export declare function verifyAgentDiscovery(binding: AgentDiscoveryBinding): void;
+export declare function rebindAgentDiscovery(binding: AgentDiscoveryBinding, changes: Map<string, string>): AgentDiscoveryBinding;
+/** 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;
+/** 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: {
+    home: string;
+    agent: IntegrationAgent;
+    reviewed?: ReviewedDiscoveryInputs;
+    canonical?: (path: string) => string;
+}): AgentDiscoveryBinding;

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

@@ -0,0 +1,30 @@
+export interface HermesSupervisorBinding {
+    path: string;
+    runtime: string;
+    sha256: string;
+}
+export declare const HERMES_OPT_OUT = ".no-bundled-skills";
+declare const EVENTS: readonly ["pre_llm_call", "pre_tool_call"];
+export declare function parseHermesConfig(text: string | null): Record<string, any>;
+export declare function hermesHookDefinitions(supervisor: Pick<HermesSupervisorBinding, "path" | "runtime">): Record<typeof EVENTS[number], {
+    command: string;
+    timeout: number;
+    fail_closed?: boolean;
+}>;
+export declare function configureHermesHooks(text: string | null, supervisor: HermesSupervisorBinding, previous?: HermesSupervisorBinding): string;
+export declare function assertHermesEnvironment(home: string): void;
+export declare function assertHermesProtection(home: string, config: Record<string, any>, command: string, profile: string, supervisor: HermesSupervisorBinding): void;
+/** skill_view also searches legacy <name>.md with rglob, including hidden and
+ * dependency directories that the normal SKILL.md index skips. Check the one
+ * name admitted by the native tool guard without reading any candidate bytes.
+ * Only support folders directly under a real skill descriptor are excluded,
+ * matching Hermes is_skill_support_path. Every other bounded path is checked. */
+export declare function assertNoHermesLegacyShadow(root: string): void;
+export declare function normalizeHermesHookInput(input: Record<string, any>): Record<string, any>;
+export declare function assertHermesTool(input: Record<string, any>): void;
+/** Hermes 0.20.5 treats some empty/non-directive child failures as no directive,
+ * even with fail_closed. This owned supervisor produces its explicit blocking
+ * wire shape and exit 2 for every observed Skills child failure. Native host or
+ * supervisor death is outside that guarantee; no native runtime is patched. */
+export declare function renderHermesSupervisor(command: string, profile: string): string;
+export {};

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

@@ -1,4 +1,6 @@
-export type IntegrationAgent = "claude" | "codex";
+import { type AgentDiscoveryBinding, type ReviewedDiscoveryInputs } from "./agent-discovery.js";
+import { type IntegrationAgent } from "./agent-adapters.js";
+export type { IntegrationAgent } from "./agent-adapters.js";
 export type ContextHookEvent = "UserPromptSubmit" | "SessionStart" | "SubagentStart";
 export interface AgentRootAlias {
     agent: IntegrationAgent;
@@ -15,6 +17,9 @@ export interface NativeSkillEntry {
     hash: string;
     managed: boolean;
     vendor: boolean;
+    system?: boolean;
+    bridge?: boolean;
+    bridgeHome?: string;
     rootAlias?: AgentRootAlias;
 }
 export interface AgentConfigChange {
@@ -27,11 +32,25 @@ export interface AgentIntegrationPlan {
     profileId: string;
     changes: AgentConfigChange[];
     nativeSkills: NativeSkillEntry[];
+    observedPolicy?: {
+        path: string;
+        before: string | null;
+    };
+    discoveryBefore?: AgentDiscoveryBinding[];
+    discoveryAfter?: AgentDiscoveryBinding[];
     rootAliases?: AgentRootAlias[];
 }
 export declare function inventoryNativeSkills(home?: string, options?: {
     includeVendor?: boolean;
+    guardHermes?: boolean;
     projectDir?: string;
+    projectDirs?: string[];
+    agentRoots?: Array<{
+        agent: string;
+        path: string;
+    }>;
+    configured?: boolean;
+    discoveryInputs?: ReviewedDiscoveryInputs;
     allowRootAliases?: boolean;
 }): NativeSkillEntry[];
 /** Planning is read-only; credentials and unrelated settings never appear in CLI output. */
@@ -43,6 +62,7 @@ export declare function planAgentIntegration(options: {
     profileId?: string;
     includeVendor?: boolean;
     projectDir?: string;
+    discoveryInputs?: ReviewedDiscoveryInputs;
     allowRootAliases?: boolean;
 }): AgentIntegrationPlan;
 export declare function applyAgentIntegration(plan: AgentIntegrationPlan): {
@@ -53,15 +73,26 @@ export declare function applyAgentIntegration(plan: AgentIntegrationPlan): {
 export declare function archiveNativeSkills(inventory: NativeSkillEntry[], options: {
     dataDir?: string;
     includeUnmanaged?: boolean;
+    includeVendor?: boolean;
     allowRootAliases?: boolean;
 }): {
     entries: Array<{
         source: string;
         archive: string;
         hash: string;
+        discoveryOnly?: boolean;
     }>;
+    receiptPath?: string;
     rootAliases?: AgentRootAlias[];
 };
+/** Run before any prompt context load. Missing ownership or reappearing native
+ * discovery files require repair; verified cache availability is not an override. */
+export declare function assertManagedAgentBridge(agent: IntegrationAgent, options?: {
+    home?: string;
+    dataDir?: string;
+    projectDir?: string;
+    projectDirs?: string[];
+}): void;
 export declare function hookContextOutput(event: string, result: {
     context: string;
     receipt?: unknown;

package/dist/lib/agent-policy-limits.d.ts

@@ -0,0 +1,13 @@
+/** Shared bounds for stored policy, discovery, and pre-activation validation. */
+export declare const AGENT_POLICY_LIMITS: Readonly<{
+    bytes: number;
+    agents: 16;
+    discoverySources: 2048;
+    discoveryRoots: 512;
+    builtinNames: 2048;
+    rootAliases: 2;
+    fields: 64;
+    pathCharacters: 4096;
+}>;
+/** Unknown extension fields remain compatible within the serialized byte bound. */
+export declare function assertAgentPolicyCollections(policy: Record<string, any>): void;

package/dist/lib/dependency-preparation.d.ts

@@ -0,0 +1,9 @@
+export declare const DEPENDENCY_PREPARATION_MARKER = ".skills-dependency-preparation";
+export declare function hasDependencyPreparationMarker(skillPath: string): boolean;
+type PreparationFailure = {
+    exitCode: number;
+    error: string;
+};
+/** Prepare in the selected corpus without exposing installer diagnostics. */
+export declare function prepareSkillDependencies(skillPath: string, env: Record<string, string | undefined>, timeoutMs?: number): Promise<PreparationFailure | undefined>;
+export {};

package/dist/lib/managed-policy.d.ts

@@ -1,4 +1,12 @@
-/** Lightweight, write-free policy check; importing agent integration would create an installer cycle. */
+/** Validate the actual wire representation shared by readers and activation. */
+export declare function parseManagedSkillPolicy(text: string): Record<string, any>;
+export declare function serializeManagedSkillPolicy(value: Record<string, any>): string;
+/** Read at most the shared byte bound, including a concurrent file growth. */
+export declare function readManagedSkillPolicySnapshot(dataDir?: string): {
+    text: string;
+    value: Record<string, any>;
+} | null;
+/** Lightweight policy check; importing agent integration would create a cycle. */
 export declare function readManagedSkillPolicy(dataDir?: string): {
     loading?: string;
     profileId?: string;

package/dist/lib/portable-skills.d.ts

@@ -35,6 +35,8 @@ export * from "./portable-skills-types.js";
  * and one rule for which source wins.
  */
 export declare function getPortableSkillsRoot(options?: PortableSkillOptions): string;
+/** Resolve an existing authoring corpus without creating or migrating directories. */
+export declare function getPortableSkillsRootReadOnly(options?: PortableSkillOptions): string;
 export declare function getPortableSkillPath(name: string, options?: PortableSkillOptions): string;
 export declare function findPortableSkill(name: string, options?: PortableSkillOptions): PortableSkillSummary | null;
 export declare function listPortableSkills(options?: PortableSkillOptions): PortableSkillSummary[];

package/dist/lib/preparation-process.d.ts

@@ -0,0 +1,13 @@
+type OwnedChild = {
+    readonly pid: number;
+    readonly exitCode: number | null;
+    readonly signalCode: string | number | null;
+    kill(signal: "SIGKILL"): unknown;
+};
+type GroupSignal = (pid: number, signal: "SIGKILL" | 0) => unknown;
+/** Capture identity immediately after spawn; Bun may change pid after reaping. */
+export declare function capturePreparationProcess(child: OwnedChild, platform?: NodeJS.Platform, signalGroup?: GroupSignal): {
+    kill(): void;
+    groupExited(): boolean | undefined;
+};
+export {};

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

@@ -0,0 +1,22 @@
+import { type PortableSkillOptions, type SkillKind } from "./portable-skills.js";
+export interface PrepareSkillOptions extends PortableSkillOptions {
+    version: string;
+    kind?: SkillKind;
+    dryRun?: boolean;
+}
+export interface PrepareSkillResult {
+    name: string;
+    path: string;
+    previousVersion: string;
+    version: string;
+    kind: SkillKind;
+    contentHash: string;
+    changed: boolean;
+    written: boolean;
+    warnings: Array<{
+        code: string;
+        message: string;
+    }>;
+}
+/** Prepare a reviewed local draft. No execution, dependency install, API call or source rewrite. */
+export declare function prepareSkill(name: string, options: PrepareSkillOptions): PrepareSkillResult;

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

@@ -0,0 +1,15 @@
+import type { ResolvedSkillProfile, SkillProfile, SkillSelection } from "../types/skill-selection.js";
+/** Shared transport and local-document limits. Operator request limits may be lower. */
+export declare const MAX_PROFILE_SELECTIONS = 4096;
+export declare const MAX_PROFILE_DOCUMENT_BYTES: number;
+export declare const MAX_SKILL_SESSION_ID_CHARS = 256;
+export declare const PROFILE_SESSION_ENVELOPE_BYTES: number;
+export declare const MAX_RESOLVED_PROFILE_BYTES: number;
+export declare const LEGACY_PROFILE_SELECTIONS = 256;
+export declare const LEGACY_PROFILE_DOCUMENT_BYTES = 1000000;
+export declare function profileDocumentBytes(value: unknown): number;
+export declare function requiresProfileCapacity(selections: SkillSelection[], bodyBytes: number): boolean;
+export declare function assertAdvertisedProfileCapacity(value: unknown, count: number, bodyBytes: number): void;
+export declare function resolvedProfileSnapshot(profile: Pick<SkillProfile, "id" | "workspaceId" | "revision" | "selections">, authority: string): ResolvedSkillProfile;
+/** Station submissions carry canonical selections, not repeated resolution metadata. */
+export declare function profileSelectionSnapshot(selections: SkillSelection[]): SkillSelection[];

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

@@ -0,0 +1,6 @@
+import type { SkillSelection } from "../types/skill-selection.js";
+/** Aliases are direct names of one pinned selection, never a second registry. */
+export declare function selectionAliasError(selections: readonly Pick<SkillSelection, "slug" | "aliases">[]): string | undefined;
+export declare function selectionMatchesName(selection: Pick<SkillSelection, "slug" | "aliases">, name: string): boolean;
+/** Ignore resolved authority fields and JSON key ordering, not contract data. */
+export declare function selectionSnapshotsEqual(left: readonly SkillSelection[], right: readonly SkillSelection[]): boolean;

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

@@ -52,6 +52,7 @@ export declare function loadSelectedSkill(spec: string, profileId: string, optio
         slug: string;
         version: string;
         bundleDigest: string;
+        aliases?: string[];
         triggers?: {
             keywords?: string[];
             paths?: string[];

package/dist/lib/skillinfo.d.ts

@@ -1,6 +1,3 @@
-/**
- * Skill info - reads docs, requirements, and metadata from skill source
- */
 import { type SkillMeta } from "./registry.js";
 export interface SkillDocs {
     skillMd: string | null;
@@ -49,6 +46,7 @@ export declare function runSkill(name: string, args: string[], options?: {
     installed?: boolean;
     stdio?: "inherit" | "pipe" | "stderr";
     env?: Record<string, string>;
+    preparationTimeoutMs?: number;
 }): Promise<{
     exitCode: number;
     error?: string;