@hasna/skills 0.5.11 → 0.6.1

package/dist/server/app.d.ts

@@ -1,5 +1,6 @@
 import { type GovernanceStore } from "../sdk/governance-store.js";
 import { ArtifactStorage } from "./artifact-storage.js";
+import { type RuntimeService } from "./runtime-api.js";
 import { type SkillsServerConfig } from "./config.js";
 import { type MemorySkillsStore } from "./store.js";
 import { type SkillsProductStore } from "./types.js";
@@ -10,7 +11,12 @@ export interface SkillsServerOptions {
     store?: SkillsProductStore;
     /** Lifecycle ledger and ceiling reads for governance surfaces (cancellation). Defaults to the store's database. */
     governanceStore?: GovernanceStore;
+    /** Inject a configured cloud runtime, or null to explicitly disable cloud execution. */
+    runtime?: RuntimeService | null;
 }
+export type SkillsFetchHandler = ((request: Request) => Promise<Response>) & {
+    close(): Promise<void>;
+};
 /**
  * Refuse to serve traffic from storage that will not survive a restart.
  *
@@ -28,7 +34,7 @@ export declare function assertDurableTarget(target: {
     durable: boolean;
     label: string;
 }, config: Pick<SkillsServerConfig, "allowEphemeralStore">): void;
-export declare function createSkillsFetchHandler(options?: SkillsServerOptions): Promise<(request: Request) => Promise<Response>>;
+export declare function createSkillsFetchHandler(options?: SkillsServerOptions): Promise<SkillsFetchHandler>;
 export declare function startSkillsServer(options?: SkillsServerOptions): Promise<Bun.Server<undefined>>;
 /**
  * Socket-level body ceiling, derived from the same setting the publish route enforces.

package/dist/server/artifact-storage.d.ts

@@ -15,6 +15,8 @@ export interface S3ClientLike {
 export interface ArtifactStorageOptions {
     bucket?: string;
     prefix?: string;
+    /** Separate expiring run outputs from durable bundle/version objects. Defaults to prefix for compatibility. */
+    runPrefix?: string;
     region?: string;
     /** Overrides the real S3 client (tests). Ignored when no bucket is configured. */
     client?: S3ClientLike;
@@ -22,6 +24,7 @@ export interface ArtifactStorageOptions {
 export declare class ArtifactStorage {
     private bucket?;
     private prefix;
+    private runPrefix;
     private s3?;
     constructor(options?: ArtifactStorageOptions);
     get usesS3(): boolean;
@@ -114,16 +117,10 @@ export declare class ArtifactStorage {
      * The content-addressed object under bundles/ stays the read path (dedupe); these keys
      * are the durable, browsable history and are never deleted by orphan collection.
      *
-     * RETENTION (hasna/apps#1671): these objects accumulate without bound by design — every
-     * version keeps a full copy — so the bucket lifecycle is the retention story, not the
-     * store. The intended rule (operated in the bucket's lifecycle config, outside this
-     * repository): expire `<prefix>/skills/` objects older than N days per the slot policy,
-     * while `<prefix>/bundles/` (content-addressed, deduped across versions and slugs) is
-     * NEVER expired by lifecycle — only the reference-guarded delete path removes those,
-     * because one object can serve many versions. A busy org that pushes thousands of
-     * versions should pair the lifecycle rule with a documented cap on retained versions
-     * per slug (e.g. the newest K, pruned by a maintenance job that deletes the version row
-     * and its two objects together); row deletion alone would strand the objects.
+     * RETENTION: neither version history nor content-addressed bundles may share an
+     * expiring lifecycle prefix with run outputs. Configure runPrefix separately for
+     * ephemeral artifacts; retain this prefix until reference-aware maintenance removes
+     * the version rows and objects together. Existing persisted storage keys remain valid.
      * Returns the placement recorded on the version row; in db mode nothing is written.
      */
     putVersionObjects(orgId: string, slug: string, version: string, bytes: OwnedBytes, manifest: Record<string, unknown>, contentType?: string): Promise<{

package/dist/server/auth.d.ts

@@ -3,3 +3,5 @@ export declare function hashApiKey(token: string): string;
 export declare function bearerToken(request: Request): string | null;
 export declare function authenticateRequest(store: SkillsProductStore, request: Request): Promise<ApiPrincipal | null>;
 export declare function publicPrincipal(partial?: Partial<ApiPrincipal>): ApiPrincipal;
+/** Scope checks apply to the key, independently of its user's workspace role. */
+export declare function permitsSkillsRoute(principal: ApiPrincipal, method: string, resource: string): boolean;

package/dist/server/config.d.ts

@@ -7,6 +7,8 @@ export interface SkillsServerConfig {
     seedBundledCorpus: boolean;
     artifactBucket?: string;
     artifactPrefix: string;
+    /** Optional expiring run-output namespace; immutable bundles retain artifactPrefix. */
+    runArtifactPrefix?: string;
     inlineWorker: boolean;
     /**
      * HMAC key for signing served skill bundles. When set, the bundle endpoint adds

package/dist/server/profile-api.d.ts

@@ -0,0 +1,3 @@
+import type { ApiPrincipal, SkillsProductStore } from "./types.js";
+import type { SkillsServerConfig } from "./config.js";
+export declare function handleProfileApi(store: SkillsProductStore, principal: ApiPrincipal, request: Request, parts: string[], config: SkillsServerConfig): Promise<Response | null>;

package/dist/server/runtime-api.d.ts

@@ -0,0 +1,31 @@
+import type { ApiPrincipal, SkillsProductStore } from "./types.js";
+import { ArtifactStorage } from "./artifact-storage.js";
+import { RuntimeExecutionStore } from "./runtime-store.js";
+import { EcsDispatcher, type EcsRunTaskClient } from "../sdk/execution/dispatchers/ecs.js";
+import { type RuntimeConfig } from "./runtime-policy.js";
+export interface RuntimeService {
+    config: RuntimeConfig;
+    signingKey: string;
+    store: RuntimeExecutionStore;
+    productStore: SkillsProductStore;
+    artifacts: ArtifactStorage;
+    dispatcher: EcsDispatcher;
+    close?: () => Promise<void>;
+}
+export declare function createRuntimeService(options: {
+    databaseUrl?: string;
+    productStore: SkillsProductStore;
+    artifacts?: ArtifactStorage;
+    env?: Record<string, string | undefined>;
+    executionStore?: RuntimeExecutionStore;
+    ecsClient?: EcsRunTaskClient;
+}): Promise<RuntimeService | null>;
+/** Called after normal bearer authentication. Dedicated paths avoid changing /runs. */
+export declare function handleRuntimeApiRequest(request: Request, principal: ApiPrincipal, service: RuntimeService | null): Promise<Response | null>;
+/** Worker-only route, before ordinary API-key auth. The token is bound to one
+ * run, attempt, generation and deadline; it cannot read the registry or another run. */
+export declare function handleRuntimeWorkerRequest(request: Request, service: RuntimeService | null): Promise<Response | null>;
+/** Replays persisted launch intents after an API restart and settles tasks that
+ * stop before they can send a completion. Lost launch observations remain
+ * unresolved: an empty eventual ECS listing must never cause a second launch. */
+export declare function reconcileRuntimeJobs(service: RuntimeService): Promise<void>;

package/dist/server/runtime-policy.d.ts

@@ -0,0 +1,25 @@
+import type { EcsDispatcherConfig } from "../sdk/execution/dispatchers/ecs.js";
+import type { FrozenAdmission, AttemptRecord } from "../sdk/execution/types.js";
+export declare const RUNTIME_MAX_INPUT_BYTES = 100000;
+export declare const RUNTIME_MAX_BUNDLE_BYTES = 1000000;
+export declare const RUNTIME_MAX_ARTIFACT_BYTES = 2000000;
+export declare const RUNTIME_MAX_LOG_BYTES = 32768;
+export declare const RUNTIME_TIMEOUT_MS = 60000;
+export interface RuntimeConfig extends EcsDispatcherConfig {
+    imageDigest: string;
+    apiOrigin: string;
+    /** Only independently reviewed exact bundles enter this first credential-free lane. */
+    reviewedBundles: {
+        slug: "pdf-generate";
+        version: string;
+        sha256: string;
+    }[];
+}
+export declare function readRuntimeConfig(env?: Record<string, string | undefined>): RuntimeConfig | null;
+export declare function runtimeInput(value: unknown): {
+    content: string;
+    title?: string;
+};
+export declare function runtimeToken(key: string, admission: FrozenAdmission, attempt: AttemptRecord): string;
+export declare function verifyRuntimeToken(token: string, key: string, admission: FrozenAdmission, attempt: AttemptRecord, now?: number): boolean;
+export declare const hashBytes: (bytes: Uint8Array) => string;

package/dist/server/runtime-store.d.ts

@@ -0,0 +1,73 @@
+import type { RunExecutionStore, CreateAttemptInput, ClaimAttemptInput, LaunchIntentResult } from "../sdk/execution/storage.js";
+import type { FrozenAdmission, ExecutionRunRow, AttemptRecord, AttemptReceipt, RunTransitionRecord, ExecutionRunStatus, TerminalRunStatus, ClaimResult } from "../sdk/execution/types.js";
+export interface RuntimeArtifact {
+    name: string;
+    contentType: string;
+    base64: string;
+    sha256: string;
+    byteSize: number;
+}
+export interface RuntimeResult {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+    artifacts: RuntimeArtifact[];
+    error?: string;
+}
+export interface RuntimeJob {
+    execution: ExecutionRunRow;
+    attempts: AttemptRecord[];
+    receipts: AttemptReceipt[];
+    transitions: RunTransitionRecord[];
+    input?: {
+        content: string;
+        title?: string;
+    };
+    bundleBase64?: string;
+    result?: RuntimeResult;
+}
+/** Each mutation locks the complete execution aggregate. Cross-process claims,
+ * cancellation and receipts cannot interleave within one run. No process-local queue. */
+export declare class RuntimeExecutionStore implements RunExecutionStore {
+    private sqlite?;
+    private postgres?;
+    readonly durable: boolean;
+    private constructor();
+    static open(databaseUrl?: string): Promise<RuntimeExecutionStore>;
+    close(): Promise<void>;
+    job(runId: string): Promise<RuntimeJob | null>;
+    mutate<T>(id: string, fn: (job: RuntimeJob) => T): Promise<T | null>;
+    admit(admission: FrozenAdmission): Promise<ExecutionRunRow>;
+    activeJobs(limit?: number): Promise<RuntimeJob[]>;
+    getRun(id: string): Promise<ExecutionRunRow | null>;
+    getRunByKey(tenant: string, key: string): Promise<ExecutionRunRow | null>;
+    getRunByDigests(input: {
+        tenantId: string;
+        skillId: string;
+        skillVersion: string;
+        bundleDigest: string;
+        inputDigest: string;
+    }): Promise<ExecutionRunRow | null>;
+    listAttempts(id: string): Promise<AttemptRecord[]>;
+    createAttempt(input: CreateAttemptInput): Promise<AttemptRecord>;
+    claimAttempt(input: ClaimAttemptInput): Promise<ClaimResult>;
+    recordLaunchIntent(input: {
+        runId: string;
+        attemptId: string;
+        clientToken: string;
+        requestDigest: string;
+        startedBy: string;
+    }): Promise<LaunchIntentResult>;
+    recordLaunchState(input: {
+        runId: string;
+        attemptId: string;
+        launchState: AttemptRecord["launchState"];
+        taskId?: string | null;
+    }): Promise<AttemptRecord | null>;
+    recordTransition(t: RunTransitionRecord): Promise<void>;
+    markAttemptTerminal(id: string, attemptId: string): Promise<AttemptRecord | null>;
+    writeReceipt(receipt: AttemptReceipt): Promise<AttemptReceipt>;
+    getReceipt(id: string, attempt: string): Promise<AttemptReceipt | null>;
+    finalizeRun(id: string, status: TerminalRunStatus, receiptId: string): Promise<ExecutionRunRow | null>;
+    setRunStatus(id: string, status: ExecutionRunStatus): Promise<ExecutionRunRow | null>;
+}

package/dist/server/runtime-worker.d.ts

@@ -0,0 +1,19 @@
+#!/usr/bin/env bun
+import type { FrozenAdmission } from "../sdk/execution/types.js";
+import type { RuntimeResult } from "./runtime-store.js";
+export interface RuntimeWork {
+    admission: FrozenAdmission;
+    bundleBase64: string;
+    input: {
+        content: string;
+        title?: string;
+    };
+}
+export interface SupervisorOptions {
+    executable?: string;
+    dependenciesPath: string;
+    unprivileged?: boolean;
+    guardPath?: string;
+}
+export declare function executeRuntimeWork(work: RuntimeWork, options: SupervisorOptions): Promise<RuntimeResult>;
+export declare function runRuntimeWorker(env?: Record<string, string | undefined>): Promise<void>;

package/dist/server/selection-store.d.ts

@@ -0,0 +1,39 @@
+import type { Database } from "bun:sqlite";
+import type { ApiPrincipal } from "./types.js";
+import type { SkillProfile, SkillSelection, StationSkillState, StationSkillStateInput } from "../types/skill-selection.js";
+export interface SkillSelectionStore {
+    getProfile(principal: ApiPrincipal, id: string): Promise<SkillProfile | null>;
+    /** null expected revision means create-only; null result means CAS conflict. */
+    saveProfile(principal: ApiPrincipal, id: string, selections: SkillSelection[], expected: string | null): Promise<SkillProfile | null>;
+    getStationState(principal: ApiPrincipal, id: string): Promise<StationSkillState | null>;
+    /** Refuses an obsolete profile revision atomically with storing the receipt. */
+    saveStationState(principal: ApiPrincipal, id: string, input: StationSkillStateInput): Promise<StationSkillState | null>;
+}
+type Row = Record<string, unknown>;
+export declare class MemorySkillSelectionStore implements SkillSelectionStore {
+    private profiles;
+    private states;
+    private key;
+    getProfile(p: ApiPrincipal, id: string): Promise<SkillProfile | null>;
+    saveProfile(p: ApiPrincipal, id: string, selected: SkillSelection[], expected: string | null): Promise<SkillProfile | null>;
+    getStationState(p: ApiPrincipal, id: string): Promise<StationSkillState | null>;
+    saveStationState(p: ApiPrincipal, id: string, input: StationSkillStateInput): Promise<StationSkillState | null>;
+}
+export declare class SqliteSkillSelectionStore implements SkillSelectionStore {
+    private db;
+    constructor(db: Database);
+    getProfile(p: ApiPrincipal, id: string): Promise<SkillProfile | null>;
+    saveProfile(p: ApiPrincipal, id: string, selected: SkillSelection[], expected: string | null): Promise<SkillProfile | null>;
+    getStationState(p: ApiPrincipal, id: string): Promise<StationSkillState | null>;
+    saveStationState(p: ApiPrincipal, id: string, input: StationSkillStateInput): Promise<StationSkillState | null>;
+}
+type Sql = (strings: TemplateStringsArray, ...values: unknown[]) => Promise<Row[]>;
+export declare class PostgresSkillSelectionStore implements SkillSelectionStore {
+    private sql;
+    constructor(sql: Sql);
+    getProfile(p: ApiPrincipal, id: string): Promise<SkillProfile | null>;
+    saveProfile(p: ApiPrincipal, id: string, selected: SkillSelection[], expected: string | null): Promise<SkillProfile | null>;
+    getStationState(p: ApiPrincipal, id: string): Promise<StationSkillState | null>;
+    saveStationState(p: ApiPrincipal, id: string, input: StationSkillStateInput): Promise<StationSkillState | null>;
+}
+export {};

package/dist/server/sqlite-store.d.ts

@@ -13,6 +13,7 @@
  * requirement; changing Postgres behaviour is not this module's job.
  */
 import { Database } from "bun:sqlite";
+import { SqliteSkillSelectionStore } from "./selection-store.js";
 import type { ApiPrincipal, ClaimRunInput, CreateRunInput, PublishSkillInput, RunTransitionPatch, ServerArtifact, ServerPin, ServerRunLog, ServerRunRecord, ServerSkillBundle, ServerSkillVersion, ServerSkillRecord, SkillsProductStore, StoreBackendInfo, UpdateSkillPatch } from "./types.js";
 export interface SqliteStoreOptions {
     /** Apply pending migrations on open. Default true - it is what makes zero-config work. */
@@ -30,6 +31,7 @@ export interface SqliteStoreOptions {
     busyTimeoutMs?: number;
 }
 export declare class SqliteSkillsStore implements SkillsProductStore {
+    get selectionStore(): SqliteSkillSelectionStore;
     readonly backend: StoreBackendInfo;
     private db;
     private closed;

package/dist/server/store.d.ts

@@ -1,3 +1,4 @@
+import { MemorySkillSelectionStore, PostgresSkillSelectionStore } from "./selection-store.js";
 import type { ApiPrincipal, ClaimRunInput, CreateRunInput, PublishSkillInput, RunTransitionPatch, ServerArtifact, ServerPin, ServerRunLog, ServerRunRecord, ServerSkillBundle, ServerSkillRecord, ServerSkillVersion, SkillsProductStore, StoreBackendInfo, UpdateSkillPatch } from "./types.js";
 import { type SqliteStoreOptions } from "./sqlite-store.js";
 export declare function createArtifactId(): string;
@@ -23,6 +24,7 @@ export interface StoreOptions {
  */
 export declare function createStore(options?: StoreOptions): Promise<SkillsProductStore>;
 export declare class MemorySkillsStore implements SkillsProductStore {
+    readonly selectionStore: MemorySkillSelectionStore;
     readonly backend: StoreBackendInfo;
     private apiKeys;
     private runs;
@@ -87,6 +89,7 @@ export declare class MemorySkillsStore implements SkillsProductStore {
     private patchRun;
 }
 export declare class PostgresSkillsStore implements SkillsProductStore {
+    get selectionStore(): PostgresSkillSelectionStore;
     readonly backend: StoreBackendInfo;
     private sql;
     constructor(databaseUrl: string);

package/dist/server/types.d.ts

@@ -1,4 +1,5 @@
 import type { OwnedBytes } from "../lib/skill-bundle.js";
+import type { SkillSelectionStore } from "./selection-store.js";
 export declare const SERVER_RUN_STATUSES: readonly ["queued", "waiting_for_approval", "running", "succeeded", "failed", "cancel_requested", "cancelled", "retrying", "expired", "refunded"];
 export type ServerRunStatus = (typeof SERVER_RUN_STATUSES)[number];
 /**
@@ -297,6 +298,8 @@ export interface SkillsProductStore {
      * actually being closed is our own default, which is now SQLite on disk.
      */
     readonly backend?: StoreBackendInfo;
+    /** Optional for third-party stores; profile APIs fail closed when absent. */
+    readonly selectionStore?: SkillSelectionStore;
     /** Release connections and file handles. Optional; not every backend holds any. */
     close?(): Promise<void>;
     /**

package/dist/types/skill-selection.d.ts

@@ -0,0 +1,41 @@
+/** Published selections are immutable references; credentials never define ownership. */
+export interface SkillSelection {
+    slug: string;
+    version: string;
+    bundleDigest: string;
+    triggers?: {
+        keywords?: string[];
+        paths?: string[];
+        always?: boolean;
+    };
+}
+export interface SkillProfile {
+    id: string;
+    workspaceId: string;
+    revision: string;
+    selections: SkillSelection[];
+    updatedAt: string;
+}
+export interface ResolvedSkillSelection extends SkillSelection {
+    authority: string;
+    workspaceId: string;
+    profileRevision: string;
+}
+export interface ResolvedSkillProfile {
+    profileId: string;
+    workspaceId: string;
+    profileRevision: string;
+    authority: string;
+    selections: ResolvedSkillSelection[];
+}
+export interface StationSkillStateInput {
+    profileId: string;
+    profileRevision: string;
+    selections: SkillSelection[];
+}
+export interface StationSkillState extends StationSkillStateInput {
+    stationId: string;
+    workspaceId: string;
+    actorId: string;
+    appliedAt: string;
+}

package/migrations/postgres/0007_skill_profiles.sql

@@ -0,0 +1,19 @@
+-- Org predicates fence every read and mutation; there is no context-less worker writer.
+CREATE TABLE IF NOT EXISTS skills_profiles (
+  org_id text NOT NULL REFERENCES organizations(id) ON DELETE CASCADE,
+  profile_id text NOT NULL,
+  revision text NOT NULL,
+  selections_json jsonb NOT NULL,
+  updated_at timestamptz NOT NULL,
+  PRIMARY KEY (org_id, profile_id)
+);
+CREATE TABLE IF NOT EXISTS skills_station_state (
+  org_id text NOT NULL REFERENCES organizations(id) ON DELETE CASCADE,
+  actor_id text NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+  station_id text NOT NULL,
+  profile_id text NOT NULL,
+  profile_revision text NOT NULL,
+  selections_json jsonb NOT NULL,
+  applied_at timestamptz NOT NULL,
+  PRIMARY KEY (org_id, actor_id, station_id)
+);

package/migrations/postgres/0008_skill_runtime.sql

@@ -0,0 +1,14 @@
+CREATE TABLE IF NOT EXISTS skills_runtime_jobs (
+  run_id TEXT PRIMARY KEY,
+  tenant_id TEXT NOT NULL,
+  idempotency_key TEXT NOT NULL,
+  skill_id TEXT NOT NULL,
+  skill_version TEXT NOT NULL,
+  bundle_digest TEXT NOT NULL,
+  input_digest TEXT NOT NULL,
+  status TEXT NOT NULL,
+  payload TEXT NOT NULL,
+  UNIQUE(tenant_id, idempotency_key)
+);
+CREATE INDEX IF NOT EXISTS skills_runtime_jobs_digests ON skills_runtime_jobs(tenant_id, skill_id, skill_version, bundle_digest, input_digest);
+CREATE INDEX IF NOT EXISTS skills_runtime_jobs_active ON skills_runtime_jobs(tenant_id, status);

package/migrations/sqlite/0007_skill_profiles.sql

@@ -0,0 +1,19 @@
+-- Desired selections belong to the workspace; receipts belong to stable actors/stations.
+CREATE TABLE IF NOT EXISTS skills_profiles (
+  org_id text NOT NULL REFERENCES organizations(id) ON DELETE CASCADE,
+  profile_id text NOT NULL,
+  revision text NOT NULL,
+  selections_json text NOT NULL,
+  updated_at text NOT NULL,
+  PRIMARY KEY (org_id, profile_id)
+);
+CREATE TABLE IF NOT EXISTS skills_station_state (
+  org_id text NOT NULL REFERENCES organizations(id) ON DELETE CASCADE,
+  actor_id text NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+  station_id text NOT NULL,
+  profile_id text NOT NULL,
+  profile_revision text NOT NULL,
+  selections_json text NOT NULL,
+  applied_at text NOT NULL,
+  PRIMARY KEY (org_id, actor_id, station_id)
+);

package/migrations/sqlite/0008_skill_runtime.sql

@@ -0,0 +1,14 @@
+CREATE TABLE IF NOT EXISTS skills_runtime_jobs (
+  run_id TEXT PRIMARY KEY,
+  tenant_id TEXT NOT NULL,
+  idempotency_key TEXT NOT NULL,
+  skill_id TEXT NOT NULL,
+  skill_version TEXT NOT NULL,
+  bundle_digest TEXT NOT NULL,
+  input_digest TEXT NOT NULL,
+  status TEXT NOT NULL,
+  payload TEXT NOT NULL,
+  UNIQUE(tenant_id, idempotency_key)
+);
+CREATE INDEX IF NOT EXISTS skills_runtime_jobs_digests ON skills_runtime_jobs(tenant_id, skill_id, skill_version, bundle_digest, input_digest);
+CREATE INDEX IF NOT EXISTS skills_runtime_jobs_active ON skills_runtime_jobs(tenant_id, status);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hasna/skills",
-  "version": "0.5.11",
+  "version": "0.6.1",
   "description": "Skills library for AI coding agents",
   "type": "module",
   "bin": {