@hasna/skills 0.1.64 → 0.1.66

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

@@ -96,7 +96,7 @@ export interface SyncSkillsOptions {
      * package root (which contains `skills/`). Takes precedence over
      * $SKILLS_SOURCE, which takes precedence over the installed corpus cache.
      * Agent-workflow skills are NOT part of the public repo corpus anymore — they
-     * moved to the private per-station store (hasna-internal/fleet-resources) and
+     * moved to the private per-station store (fleet-resources) and
      * reach sync through the installed cache — so a package root resolves to
      * `skills/` only.
      */
@@ -118,7 +118,7 @@ export interface SyncSkillsResult {
  *      resolved through `resolveCorpusRoot` so a migrated owner layout
  *      (~/.hasna/skills/skills/) is read in preference to `installed/`. This cache is
  *      also where private agent-workflow skills arrive from the per-station store
- *      (hasna-internal/fleet-resources) and get synced into agent folders.
+ *      (fleet-resources) and get synced into agent folders.
  *
  * A missing explicit source is an error, not a fallback to "nothing": the whole point
  * of zero-corpus is that sync must not silently sync an empty corpus because the

package/dist/lib/native-storage.d.ts

@@ -87,6 +87,34 @@ export declare const SKILLS_STORAGE_FALLBACK_ENV: {
     readonly syncBatchSize: "SKILLS_SYNC_BATCH_SIZE";
     readonly dryRun: "SKILLS_SYNC_DRY_RUN";
 };
+/**
+ * Compatibility contract for the `./storage` subpath (`@hasna/skills/storage`).
+ *
+ * Consumers — including private SaaS embedders — compile against this subpath.
+ * `version` is the contract version: it MUST be bumped on every breaking
+ * removal or rename of a listed member. `values` are the runtime exports
+ * (functions, classes, constants) and `types` the type-only exports the
+ * subpath guarantees; `src/storage-boundary.test.ts` imports the subpath and
+ * fails if a listed member is no longer exported, so a removal cannot land
+ * silently.
+ *
+ * The retirement this contract exists to make unrepeatable: in 0.1.61 the
+ * storage-mode label functions, their mode type, and the storage-mode env
+ * variables were removed from both the main entrypoint and this subpath (see
+ * the CHANGELOG entry for 0.1.61, "the deployment 'mode' concept is gone").
+ * Nothing replaced them with a successor — the mode concept is gone and must
+ * not be reintroduced. The replacement for the old question ("which mode am I
+ * in?") is configuration-derived status: call
+ * `getSkillsNativeStorageStatus()` (aliases `getSkillsStorageStatus` /
+ * `getStorageStatus`) and read `remote.databaseConfigured` /
+ * `remote.s3Configured`. On-box SQLite and files are always present; Postgres
+ * and S3 are used when, and only when, their variables are set.
+ */
+export declare const storageCapabilities: {
+    readonly version: 1;
+    readonly values: readonly ["SKILLS_NATIVE_STORAGE_ENV", "SKILLS_NATIVE_STORAGE_FALLBACK_ENV", "SKILLS_STORAGE_ENV", "SKILLS_STORAGE_FALLBACK_ENV", "SKILLS_STORAGE_TABLES", "STORAGE_TABLES", "SkillsPostgresSyncStore", "SkillsS3ObjectStore", "buildSkillsS3ObjectUrl", "createSkillsPostgresSyncStore", "createSkillsS3ObjectStore", "createSkillsSnapshotSyncRecord", "exportSkillsLocalSnapshot", "getSkillsNativeStorageStatus", "getSkillsStorageDatabaseEnv", "getSkillsStorageDatabaseUrl", "getSkillsStorageStatus", "getStorageDatabaseEnv", "getStorageDatabaseUrl", "getStorageStatus", "importSkillsLocalSnapshot", "planSkillsS3SnapshotUpload", "resolveSkillsNativeStorageConfig", "resolveStorageConfig", "signSkillsAwsV4Request", "skillsPostgresSyncSchemaSql", "storageCapabilities", "uploadSkillsSnapshotFilesToS3"];
+    readonly types: readonly ["AwsCredentials", "SignSkillsAwsV4RequestOptions", "SkillsFetch", "SkillsLocalSnapshot", "SkillsNativeStorageConfig", "SkillsNativeStorageStatus", "SkillsPostgresQueryClient", "SkillsS3ObjectStoreOptions", "SkillsS3PutObjectOptions", "SkillsS3SnapshotPlanEntry", "SkillsS3StoredObject", "SkillsSnapshotFile", "SkillsStorageTable", "SkillsSyncRecord"];
+};
 export declare function resolveSkillsNativeStorageConfig(env?: Record<string, string | undefined>): SkillsNativeStorageConfig;
 export declare function resolveStorageConfig(env?: Record<string, string | undefined>): SkillsNativeStorageConfig;
 export declare function getSkillsStorageDatabaseEnv(env?: Record<string, string | undefined>): string;

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

@@ -98,5 +98,19 @@ export interface WriteCorpusSkillInput {
  * skill — but removes nothing else, so a re-pull never destroys sibling files.
  */
 export declare function writeCorpusSkill(input: WriteCorpusSkillInput, options?: PortableSkillOptions): PortableSkillWriteResult;
+/**
+ * Atomically replace the corpus entry for a metadata-only pull (todos b4d956a3):
+ * stage SKILL.md and skill.json in a sibling directory, then rename into place — the
+ * existing entry is moved aside first and removed only after the staged tree is in
+ * position. A failure at any point leaves either the old entry or nothing — never a
+ * partial skill, mirroring installBundleAtomically on the bundle path.
+ *
+ * The manifest construction is identical to writeCorpusSkill; what differs is that no
+ * write ever lands in the live target before the swap. The direct-overwrite order of
+ * writeCorpusSkill (SKILL.md, then skill.json) can destroy the prior good copy when a
+ * mid-write failure (ENOSPC, EISDIR, crash) hits between the two writes, leaving a
+ * truncated or mismatched SKILL.md/skill.json pair that loadRegistry then serves.
+ */
+export declare function installCorpusSkillAtomically(input: WriteCorpusSkillInput, options?: PortableSkillOptions): PortableSkillWriteResult;
 export declare function validatePortableSkillDirectory(name: string, skillPath: string): SkillValidationResult;
 export declare function runPortableSkill(name: string, args: string[], options?: PortableSkillRunOptions): Promise<PortableSkillRunResult>;

package/dist/lib/registry-types.d.ts

@@ -20,6 +20,15 @@ export interface SkillMeta {
     kind?: SkillKind;
     availability?: SkillAvailabilityMetadata;
     source?: SkillSource;
+    /**
+     * Execution is server-owned per the published-skill contract: the skill's
+     * package.json declares `skills.runtime: "hosted"` or `skills.source:
+     * "remote" | "private-hosted"` (see isHostedMetadataPackage in
+     * hosted-skill-set.ts). A server-owned skill is submitted to the configured
+     * Skills API and never falls back to local execution (see resolveRunRouting
+     * in run-routing.ts). Absent means local execution is the contract.
+     */
+    serverOwned?: boolean;
 }
 export interface SkillAvailabilityMetadata {
     status: "available" | "unavailable";

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

@@ -0,0 +1,60 @@
+/**
+ * run-routing.ts — where a skill run executes: on this machine, or on the
+ * configured Skills API.
+ *
+ * One resolver serves every run surface (the CLI `skills run` path, the MCP
+ * `run_skill` tool, and the `skills schedule run` surface) so they cannot drift
+ * apart.
+ *
+ * A skill run is REMOTE only when all three hold:
+ *
+ *   1. an origin is configured (config `apiUrl` or `$SKILLS_API_URL`);
+ *   2. a credential is present (`$SKILLS_API_KEY` / `$SKILL_API_KEY` or the
+ *      auth store written by `skills auth login`);
+ *   3. the skill carries the server-owned marker from its published contract
+ *      (`skills.runtime: "hosted"` or `skills.source: "remote" |
+ *      "private-hosted"` in the skill's `package.json` — see
+ *      isHostedMetadataPackage in hosted-skill-set.ts).
+ *
+ * Otherwise the run is LOCAL, and local stays the default: an unconfigured
+ * install never sends anything anywhere.
+ *
+ * A server-owned skill never falls back to local execution. Without the origin
+ * or the credential the resolver fails closed with an error naming the exact
+ * setup command, per the product brief: "Premium or server-executed skills
+ * fail closed without API credentials and do not fall back to bundled local
+ * execution."
+ *
+ * Premium-catalog and pricing metadata is server-side and never ships in this
+ * package; the resolver concerns routing only.
+ */
+import type { SkillMeta } from "./registry-types.js";
+export type RunRoutingErrorCode = "REMOTE_REQUIRES_ORIGIN" | "REMOTE_REQUIRES_CREDENTIAL";
+export type RunRouting = {
+    route: "remote";
+    apiKey: string;
+} | {
+    route: "local";
+} | {
+    route: "error";
+    code: RunRoutingErrorCode;
+    error: string;
+};
+/**
+ * Is execution of this skill server-owned per its published contract?
+ * The marker is the skill contract's declaration; absent means local
+ * execution is the contract.
+ */
+export declare function isServerOwnedSkill(skill: Pick<SkillMeta, "serverOwned">): boolean;
+/**
+ * Decide the route for one skill run from injectable inputs, so tests can mock
+ * the origin and the credential without touching the ambient environment.
+ */
+export declare function resolveRunRouting(skill: Pick<SkillMeta, "name" | "serverOwned">, apiKey: string | null | undefined, apiUrl: string | undefined): RunRouting;
+/**
+ * Resolve the route against the ambient configuration and credential store.
+ * The returned `apiKey` on the remote route is the same value the resolver
+ * validated, so the caller never re-reads (and cannot diverge from) the
+ * credential the decision was made with.
+ */
+export declare function resolveConfiguredRunRouting(skill: Pick<SkillMeta, "name" | "serverOwned">): RunRouting;