@hasna/skills 0.5.11 → 0.6.1

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

@@ -0,0 +1,74 @@
+export type IntegrationAgent = "claude" | "codex";
+export type ContextHookEvent = "UserPromptSubmit" | "SessionStart" | "SubagentStart";
+export interface AgentRootAlias {
+    agent: IntegrationAgent;
+    home: string;
+    alias: string;
+    target: string;
+    link: string;
+    aliasIdentity: string;
+    targetIdentity: string;
+}
+export interface NativeSkillEntry {
+    agent: string;
+    path: string;
+    hash: string;
+    managed: boolean;
+    vendor: boolean;
+    rootAlias?: AgentRootAlias;
+}
+export interface AgentConfigChange {
+    path: string;
+    before: string | null;
+    after: string;
+}
+export interface AgentIntegrationPlan {
+    dataDir: string;
+    profileId: string;
+    changes: AgentConfigChange[];
+    nativeSkills: NativeSkillEntry[];
+    rootAliases?: AgentRootAlias[];
+}
+export declare function inventoryNativeSkills(home?: string, options?: {
+    includeVendor?: boolean;
+    projectDir?: string;
+    allowRootAliases?: boolean;
+}): NativeSkillEntry[];
+/** Planning is read-only; credentials and unrelated settings never appear in CLI output. */
+export declare function planAgentIntegration(options: {
+    home?: string;
+    dataDir?: string;
+    agents: IntegrationAgent[];
+    command?: string;
+    profileId?: string;
+    includeVendor?: boolean;
+    projectDir?: string;
+    allowRootAliases?: boolean;
+}): AgentIntegrationPlan;
+export declare function applyAgentIntegration(plan: AgentIntegrationPlan): {
+    changed: string[];
+    backups: string[];
+    rootAliases?: AgentRootAlias[];
+};
+export declare function archiveNativeSkills(inventory: NativeSkillEntry[], options: {
+    dataDir?: string;
+    includeUnmanaged?: boolean;
+    allowRootAliases?: boolean;
+}): {
+    entries: Array<{
+        source: string;
+        archive: string;
+        hash: string;
+    }>;
+    rootAliases?: AgentRootAlias[];
+};
+export declare function hookContextOutput(event: string, result: {
+    context: string;
+    receipt?: unknown;
+    omitted?: Array<{
+        slug: string;
+        version: string;
+        loadCommand: string;
+    }>;
+}): Record<string, unknown>;
+export declare function assertNativeExportAllowed(dataDir?: string): void;

package/dist/lib/cloud-executions.d.ts

@@ -0,0 +1,39 @@
+export interface CloudExecution {
+    contractVersion: 1;
+    id: string;
+    target: "cloud";
+    skill: string;
+    version: string;
+    bundleDigest: string;
+    inputDigest: string;
+    runtimeImageDigest: string;
+    status: "admitted" | "leased" | "running" | "succeeded" | "failed" | "cancelled";
+    exitCode?: number;
+    artifacts: {
+        name: string;
+        contentType: string;
+        sha256: string;
+        byteSize: number;
+    }[];
+}
+export declare class CloudExecutionClient {
+    private apiOrigin;
+    private apiKey;
+    constructor(apiOrigin: string, apiKey: string);
+    static configured(): Promise<CloudExecutionClient>;
+    private request;
+    submit(slug: string, version: string, input: unknown, key: string, selection?: {
+        bundleDigest: string;
+        workspaceId?: string;
+        authority?: string;
+    }): Promise<CloudExecution>;
+    get(id: string): Promise<CloudExecution>;
+    logs(id: string): Promise<unknown>;
+    artifacts(id: string): Promise<CloudExecution["artifacts"]>;
+    download(id: string, name: string): Promise<Uint8Array>;
+    cancel(id: string): Promise<CloudExecution>;
+    wait(id: string, options?: {
+        timeoutMs?: number;
+        intervalMs?: number;
+    }): Promise<CloudExecution>;
+}

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

@@ -0,0 +1,6 @@
+/** Lightweight, write-free policy check; importing agent integration would create an installer cycle. */
+export declare function readManagedSkillPolicy(dataDir?: string): {
+    loading?: string;
+    profileId?: string;
+} | null;
+export declare function requiresCliSkillLoading(dataDir?: string): boolean;

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

@@ -0,0 +1,4 @@
+import type { SkillProfile, SkillSelection, StationSkillState } from "../types/skill-selection.js";
+export declare function readSkillProfile(profileId: string): Promise<SkillProfile>;
+export declare function saveSkillProfile(profileId: string, selections: SkillSelection[], revision?: string): Promise<SkillProfile>;
+export declare function readStationSkillState(stationId: string): Promise<StationSkillState>;

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

@@ -0,0 +1,19 @@
+import type { ResolvedSkillProfile, StationSkillState, StationSkillStateInput } from "../types/skill-selection.js";
+export interface ProfileClient {
+    readonly authority: string;
+    resolveProfile(id: string): Promise<ResolvedSkillProfile>;
+    recordStation(id: string, state: StationSkillStateInput): Promise<StationSkillState>;
+    getBundle(slug: string, version: string): Promise<Response | null>;
+}
+export declare class HttpProfileClient implements ProfileClient {
+    private key;
+    readonly authority: string;
+    private origin;
+    constructor(key: string, origin: string);
+    private request;
+    private read;
+    resolveProfile(id: string): Promise<ResolvedSkillProfile>;
+    recordStation(id: string, input: StationSkillStateInput): Promise<StationSkillState>;
+    getBundle(slug: string, version: string): Promise<Response | null>;
+}
+export declare function createProfileClient(): Promise<ProfileClient>;

package/dist/lib/read-access.d.ts

@@ -52,29 +52,9 @@ export declare function requireSkillsReadAccess(env?: Env, options?: SkillsFleet
  * The registry a browsing surface should show — the CLI's `list` / `search` /
  * `categories` / `tags` and the MCP discovery tools, from ONE implementation.
  *
- * The default read path is folder UNION cloud: whenever the install is pointed
- * at a hosted instance (a resolved credential, and HASNA_SKILLS_API_URL for your
- * own instance) the authenticated remote registry joins the local listing even
- * without `--remote`. The explicit local opt-in keeps today's exact local
- * output; an unconfigured or auth-missing install is a refusal, thrown from the
- * shared ladder (fail-closed R1 — see mergeRemoteRegistry()).
- *
- * `--remote` used to REPLACE the local registry: `skills list --remote` returned exactly
- * what the instance served and nothing else, so the bundled corpus and every skill the
- * operator had written locally disappeared from the listing the moment they pointed the
- * CLI at their own server. It now MERGES, under the precedence documented in
- * src/lib/registry-merge.ts: custom > extension > local > remote > official, "whichever
- * copy this machine would actually use wins the listing".
- *
- * The profile (`all` vs the curated basic set) applies to the local half only. The
- * instance's skills are never filtered by it: the basic profile is a hand-written list of
- * ten bundled names, so applying it to remote entries would drop every published skill
- * from `skills list --remote` - the same disappearance this change exists to fix.
- *
- * A remote failure is still fatal. An explicit `--remote` request (and a configured,
- * authenticated default read) that fails surfaces a clear error, and silently returning
- * the local half of a merge the user asked to include the remote half in would report
- * success for a listing that is missing entries.
+ * A configured API is authoritative. Drafts and extension folders cannot shadow
+ * published metadata. Local authoring discovery requires the explicit local opt-in;
+ * authentication and network failures never fall back to local content.
  */
 export declare function getBrowseRegistry(options?: {
     all?: boolean;

package/dist/lib/selected-document.d.ts

@@ -0,0 +1,6 @@
+/** Documentation comes only from the already verified selected bundle. */
+import type { SkillBundleEntry } from "./skill-bundle.js";
+export declare function readSelectedDocument(entries: SkillBundleEntry[], file?: string): {
+    file: string;
+    content: string;
+};

package/dist/lib/selected-run.d.ts

@@ -0,0 +1,31 @@
+import type { ResolvedSkillSelection } from "../types/skill-selection.js";
+import type { SkillBundleEntry } from "./skill-bundle.js";
+import { type SelectionResolverOptions } from "./selection-resolver.js";
+export interface ResolvedSelectedRun {
+    selection: ResolvedSkillSelection;
+    kind: "instruction" | "executable";
+    entries: SkillBundleEntry[];
+    manifest: Record<string, any>;
+    packageJson: Record<string, any>;
+    cacheDir: string;
+}
+export declare function resolveSelectedRun(spec: string, profileId: string, options?: SelectionResolverOptions): Promise<ResolvedSelectedRun>;
+export interface SelectedLocalRunOptions {
+    args?: string[];
+    input?: unknown;
+    cwd?: string;
+    timeoutMs?: number;
+    /** Only explicitly supplied environment values are available to declared secret references. */
+    env?: Record<string, string>;
+}
+export declare function executeSelectedLocal(selected: ResolvedSelectedRun, options?: SelectedLocalRunOptions): Promise<{
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+    error?: string;
+    selection: ResolvedSkillSelection;
+    target: "local";
+    runtime: any;
+    inputDigest: string;
+    runDirectory: string;
+}>;

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

@@ -0,0 +1,40 @@
+import { type SkillBundleEntry } from "./skill-bundle.js";
+import type { ResolvedSkillProfile, ResolvedSkillSelection } from "../types/skill-selection.js";
+export declare class SkillSelectionError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+export interface SelectionCacheOptions {
+    cacheDir?: string;
+    now?: () => number;
+}
+export interface CachedSelectionProfile {
+    schemaVersion: 1;
+    verifiedAt: string;
+    profile: ResolvedSkillProfile;
+}
+export interface SkillSessionReceipt extends CachedSelectionProfile {
+    sessionId: string;
+    loaded: string[];
+}
+export declare const MAX_CACHED_PROFILE_AGE_MS: number;
+export declare const SELECTION_LOCK_FILE = "selection.lock.json";
+export declare function selectionCacheRoot(options?: SelectionCacheOptions): string;
+export declare function selectionKey(selection: ResolvedSkillSelection): string;
+export declare function validateSelection(selection: ResolvedSkillSelection): void;
+export declare function validateResolvedProfile(profile: ResolvedSkillProfile, authority?: string): void;
+export declare function selectionBundlePath(selection: ResolvedSkillSelection, options?: SelectionCacheOptions): string;
+export declare function writeSelectionJson(path: string, value: unknown): void;
+export declare function readSelectionJson<T>(path: string): T | null;
+export declare function readCachedSelection(selection: ResolvedSkillSelection, options?: SelectionCacheOptions): Promise<SkillBundleEntry[] | null>;
+export declare function cacheSelectionBundle(selection: ResolvedSkillSelection, response: Response | null, options?: SelectionCacheOptions): Promise<SkillBundleEntry[]>;
+export declare function activateSelectionProfile(profile: ResolvedSkillProfile, options?: SelectionCacheOptions): CachedSelectionProfile;
+export declare function readSelectionProfile(profileId: string, options?: SelectionCacheOptions): CachedSelectionProfile | null;
+export declare function validateSelectionReceipt(receipt: CachedSelectionProfile): void;
+export declare function assertFreshCachedProfile(receipt: CachedSelectionProfile, options?: SelectionCacheOptions & {
+    maxAgeMs?: number;
+}): void;
+export declare function projectSelectionLockPath(projectDir: string): string;
+export declare function readProjectSelection(projectDir: string): CachedSelectionProfile | null;
+export declare function sessionReceiptPath(sessionId: string, options?: SelectionCacheOptions): string;
+export declare function readSkillSession(sessionId: string, options?: SelectionCacheOptions): SkillSessionReceipt | null;

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

@@ -0,0 +1,75 @@
+/** One resolution path for API-selected content. Local drafts cannot shadow a published selection. */
+import { type ProfileClient } from "./profile-client.js";
+import type { ResolvedSkillProfile, ResolvedSkillSelection } from "../types/skill-selection.js";
+import type { SkillBundleEntry } from "./skill-bundle.js";
+import { type CachedSelectionProfile, type SelectionCacheOptions, type SkillSessionReceipt } from "./selection-cache.js";
+export interface SelectionResolverOptions extends SelectionCacheOptions {
+    client?: ProfileClient;
+    cached?: boolean;
+    /** Explicit cached authority binding, checked even when no credential is read. */
+    authority?: string;
+    workspaceId?: string;
+    maxAgeMs?: number;
+    projectDir?: string;
+    sessionId?: string;
+    /** A newly spawned subagent inherits the parent's pinned snapshot, never its dedup state. */
+    parentSessionId?: string;
+}
+export interface SyncSelectionProfileOptions extends SelectionCacheOptions {
+    client?: ProfileClient;
+    projectDir?: string;
+    stationId?: string;
+    check?: boolean;
+}
+export declare function syncSelectionProfile(profileId: string, options?: SyncSelectionProfileOptions): Promise<{
+    profile: ResolvedSkillProfile;
+    receipt: CachedSelectionProfile | null;
+    changed: boolean;
+    downloaded: number;
+    stationReported: boolean;
+}>;
+export interface ResolvedSelectionContext {
+    receipt: CachedSelectionProfile;
+    session: SkillSessionReceipt | null;
+    inheritedLoaded?: string[];
+    client?: ProfileClient;
+}
+export declare function resolveSelectionContext(profileId: string, options?: SelectionResolverOptions): Promise<ResolvedSelectionContext>;
+export declare function readSelectedEntries(selection: ResolvedSkillSelection, context: ResolvedSelectionContext, options?: SelectionResolverOptions): Promise<SkillBundleEntry[]>;
+export declare function exactProfileSelection(spec: string, profile: ResolvedSkillProfile): ResolvedSkillSelection;
+export declare function loadSelectedSkill(spec: string, profileId: string, options?: SelectionResolverOptions & {
+    file?: string;
+}): Promise<{
+    content: string;
+    selection: ResolvedSkillSelection;
+    receipt: {
+        file: string;
+        source: string;
+        verifiedAt: string;
+        authority: string;
+        workspaceId: string;
+        profileRevision: string;
+        slug: string;
+        version: string;
+        bundleDigest: string;
+        triggers?: {
+            keywords?: string[];
+            paths?: string[];
+            always?: boolean;
+        };
+    };
+}>;
+/** Pin the resolved profile metadata without copying a definition into the project. */
+export declare function pinSelectedSkillVersion(spec: string, profileId: string, options: SelectionResolverOptions & {
+    projectDir: string;
+}): Promise<{
+    selection: ResolvedSkillSelection;
+    path: string;
+}>;
+export declare function selectedSkillRequirements(spec: string, profileId: string, options?: SelectionResolverOptions): Promise<{
+    selection: ResolvedSkillSelection;
+    envVars: string[];
+    systemDeps: string[];
+    cliCommand: string | null;
+    dependencies: Record<string, string>;
+}>;

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

@@ -0,0 +1,43 @@
+import type { ResolvedSkillSelection } from "../types/skill-selection.js";
+import { type SelectionResolverOptions } from "./selection-resolver.js";
+export interface SkillContextInput {
+    prompt?: string;
+    cwd?: string;
+    sessionId?: string;
+    profileId?: string;
+    restore?: boolean;
+    agentId?: string;
+    skills?: string[];
+    paths?: string[];
+}
+export interface SkillContextOptions extends SelectionResolverOptions {
+    maxChars?: number;
+    maxSkills?: number;
+}
+export interface ContextSelectionReceipt extends ResolvedSkillSelection {
+    reason: string;
+}
+export interface SkillContextResult {
+    context: string;
+    selections: ContextSelectionReceipt[];
+    omitted: Array<{
+        slug: string;
+        version: string;
+        reason: string;
+        loadCommand: string;
+    }>;
+    receipt: {
+        schemaVersion: 1;
+        id: string;
+        profileId: string;
+        profileRevision: string;
+        authority: string;
+        workspaceId: string;
+        source: "api" | "verified-cache";
+        sessionId?: string;
+        restored: boolean;
+        chars: number;
+        selections: ContextSelectionReceipt[];
+    };
+}
+export declare function buildSkillContext(input: SkillContextInput, options?: SkillContextOptions): Promise<SkillContextResult>;

package/dist/lib/skillinfo.d.ts

@@ -25,6 +25,8 @@ export declare function getSkillBestDoc(name: string): string | null;
  * Extract requirements from a skill's source files
  */
 export declare function getSkillRequirements(name: string): SkillRequirements | null;
+/** Shared parser for verified bundle content and explicit local authoring files. */
+export declare function getSkillRequirementsFromContent(name: string, texts: string[], dependencies?: Record<string, string>, meta?: SkillMeta): SkillRequirements;
 export interface SkillDependencyStatus {
     name: string;
     version: string;

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

@@ -82,6 +82,13 @@ export interface EcsDispatcherOptions {
     /** Claim identity; defaults to "dispatcher". */
     workerId?: string;
     now?: () => Date;
+    /** Trusted per-attempt supervisor transport. Must be deterministic for the frozen
+     * admission: a replay keeps the identical ECS clientToken and request. Never
+     * inherited by the skill process. */
+    supervisorEnvironment?: (admission: FrozenAdmission, attempt: AttemptRecord) => {
+        name: string;
+        value: string;
+    }[];
 }
 export type LaunchOutcome = {
     kind: "launched";
@@ -128,6 +135,7 @@ export declare class EcsDispatcher implements Dispatcher {
     private readonly receipts;
     private readonly workerId;
     private readonly now;
+    private readonly supervisorEnvironment;
     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>;

package/dist/sdk/index.d.ts

@@ -15,6 +15,8 @@
  * — the shared @hasna/contracts ladder — instead of reading an environment
  * variable of its own. See lib/fleet-credentials.ts.
  */
+export { HttpProfileClient, createProfileClient, type ProfileClient } from "../lib/profile-client.js";
+export type { SkillSelection, SkillProfile, ResolvedSkillSelection, ResolvedSkillProfile, StationSkillStateInput, StationSkillState } from "../types/skill-selection.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";