@cats-inc/cats-platform 0.1.21 → 0.2.8

package/build/server/shared/runtimeSetup.d.ts

@@ -1,10 +1,23 @@
-export type RuntimeSetupStatus = 'ready' | 'ready_to_apply' | 'scan_required' | 'attention_required' | 'unavailable';
+export type RuntimeSetupStatus = 'ready' | 'selection_required' | 'scan_required' | 'attention_required' | 'unavailable';
 export type RuntimeSetupStateStatus = 'pending' | 'scanning' | 'ready' | 'applied' | 'error' | 'unavailable';
 export interface RuntimeSetupProviderSummary {
     provider: string;
     family: string;
     remediationCount?: number;
 }
+export interface RuntimeSelectedProviderTarget {
+    provider: string;
+    backend: 'cli' | 'api' | 'local' | 'agent';
+    instance: string;
+}
+export interface RuntimeProviderSelection {
+    state: 'missing' | 'invalid' | 'empty' | 'selected';
+    revision: string;
+    targets: RuntimeSelectedProviderTarget[];
+    nativeSetupTargets: RuntimeSelectedProviderTarget[];
+    diskChanged: boolean;
+    error: string | null;
+}
 export interface RuntimeSetupSummary {
     source: 'runtime' | 'assumed_ready' | 'unavailable';
     bootstrapRequired: boolean;
@@ -16,11 +29,11 @@ export interface RuntimeSetupSummary {
     appliedAt: string | null;
     providerCount: number;
     availableCount: number;
-    providersReadyToApply: RuntimeSetupProviderSummary[];
+    providersReady: RuntimeSetupProviderSummary[];
     providersNeedingAttention: RuntimeSetupProviderSummary[];
-    suggestedProviders: string[];
+    selectedProviders: string[];
     canRunManualScan: boolean;
-    canApply: boolean;
+    canManageSelection: boolean;
     error: string | null;
 }
 //# sourceMappingURL=runtimeSetup.d.ts.map

package/build/server/shared/runtimeSetup.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runtimeSetup.d.ts","sourceRoot":"","sources":["../../../src/shared/runtimeSetup.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,kBAAkB,GAC1B,OAAO,GACP,gBAAgB,GAChB,eAAe,GACf,oBAAoB,GACpB,aAAa,CAAC;AAElB,MAAM,MAAM,uBAAuB,GAC/B,SAAS,GACT,UAAU,GACV,OAAO,GACP,SAAS,GACT,OAAO,GACP,aAAa,CAAC;AAElB,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,SAAS,GAAG,eAAe,GAAG,aAAa,CAAC;IACpD,iBAAiB,EAAE,OAAO,CAAC;IAC3B,MAAM,EAAE,kBAAkB,CAAC;IAC3B,WAAW,EAAE,uBAAuB,CAAC;IACrC,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC;IACvB,qBAAqB,EAAE,2BAA2B,EAAE,CAAC;IACrD,yBAAyB,EAAE,2BAA2B,EAAE,CAAC;IACzD,kBAAkB,EAAE,MAAM,EAAE,CAAC;IAC7B,gBAAgB,EAAE,OAAO,CAAC;IAC1B,QAAQ,EAAE,OAAO,CAAC;IAClB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB"}
+{"version":3,"file":"runtimeSetup.d.ts","sourceRoot":"","sources":["../../../src/shared/runtimeSetup.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,kBAAkB,GAC1B,OAAO,GACP,oBAAoB,GACpB,eAAe,GACf,oBAAoB,GACpB,aAAa,CAAC;AAElB,MAAM,MAAM,uBAAuB,GAC/B,SAAS,GACT,UAAU,GACV,OAAO,GACP,SAAS,GACT,OAAO,GACP,aAAa,CAAC;AAElB,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,KAAK,GAAG,KAAK,GAAG,OAAO,GAAG,OAAO,CAAC;IAC3C,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,wBAAwB;IACvC,KAAK,EAAE,SAAS,GAAG,SAAS,GAAG,OAAO,GAAG,UAAU,CAAC;IACpD,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,6BAA6B,EAAE,CAAC;IACzC,kBAAkB,EAAE,6BAA6B,EAAE,CAAC;IACpD,WAAW,EAAE,OAAO,CAAC;IACrB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AAED,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,SAAS,GAAG,eAAe,GAAG,aAAa,CAAC;IACpD,iBAAiB,EAAE,OAAO,CAAC;IAC3B,MAAM,EAAE,kBAAkB,CAAC;IAC3B,WAAW,EAAE,uBAAuB,CAAC;IACrC,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC;IACvB,cAAc,EAAE,2BAA2B,EAAE,CAAC;IAC9C,yBAAyB,EAAE,2BAA2B,EAAE,CAAC;IACzD,iBAAiB,EAAE,MAAM,EAAE,CAAC;IAC5B,gBAAgB,EAAE,OAAO,CAAC;IAC1B,kBAAkB,EAAE,OAAO,CAAC;IAC5B,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB"}

package/build/server/shared/runtimeStatusPresentation.js

@@ -51,7 +51,7 @@ export function resolveRuntimeDotClassName(status) {
     }
 }
 export function needsRuntimeSetupRecovery(runtimeSetupStatus) {
-    return runtimeSetupStatus === 'ready_to_apply'
+    return runtimeSetupStatus === 'selection_required'
         || runtimeSetupStatus === 'scan_required'
         || runtimeSetupStatus === 'attention_required'
         || runtimeSetupStatus === 'unavailable';

package/build/server/shared/runtimeStatusPresentation.js.map

@@ -1 +1 @@
-{"version":3,"file":"runtimeStatusPresentation.js","sourceRoot":"","sources":["../../../src/shared/runtimeStatusPresentation.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"runtimeStatusPresentation.js","sourceRoot":"","sources":["../../../src/shared/runtimeStatusPresentation.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,10 +1,13 @@
 {
   "name": "@cats-inc/cats-platform",
-  "version": "0.1.21",
+  "version": "0.2.8",
   "description": "Technical host package for the Cats platform, backed by cats-runtime.",
   "author": "Cats Inc. <sammykenny2@gmail.com>",
   "homepage": "https://github.com/cats-inc/cats-platform",
   "type": "module",
+  "imports": {
+    "#cats-app-package": "./packages/app-sdk/package.js"
+  },
   "bin": {
     "cats-platform": "build/server/index.js"
   },
@@ -14,6 +17,7 @@
     "build/server",
     "build/desktop",
     "scripts",
+    "packages/app-sdk",
     "config/provider-capability-bootstrap.yaml.example",
     ".env.example",
     "README.md",
@@ -126,12 +130,23 @@
     },
     "files": [
       "build/desktop/**/*",
+      "packages/app-sdk/**/*",
       "assets/build/icon.ico",
       "assets/build/icon.png",
       "assets/tray-icon*.png",
       "package.json"
     ],
     "extraResources": [
+      {
+        "from": "build/desktop-packaging/shared/official-apps",
+        "to": "app-sidecar/official-apps",
+        "filter": ["**/*"]
+      },
+      {
+        "from": "build/desktop-packaging/shared/app-sidecar/packages/app-sdk",
+        "to": "app-sidecar/packages/app-sdk",
+        "filter": ["**/*"]
+      },
       {
         "from": "build/desktop-packaging/shared/build/server",
         "to": "app-sidecar/build/server",
@@ -146,6 +161,13 @@
           "**/*"
         ]
       },
+      {
+        "from": "build/desktop-packaging/shared/cats-platform/config",
+        "to": "app-sidecar/config",
+        "filter": [
+          "**/*"
+        ]
+      },
       {
         "from": "build/desktop-packaging/shared/app-sidecar/package.json",
         "to": "app-sidecar/package.json"

package/packages/app-sdk/browser.d.ts

@@ -0,0 +1,51 @@
+/** Host-injected browser API. No imports, secrets, filesystem or general network proxy. */
+export interface CatsAppBrowserSdkV1 {
+  readonly sdkVersion: '1.2.0';
+  readonly appId: string;
+  readonly version: string;
+  readonly locale: string;
+  readonly theme: 'light' | 'dark';
+  readonly usage: {
+    getSnapshot(): Promise<UsageSnapshotV1>;
+    refreshQuota(target: { provider: 'codex' | 'copilot' | 'claude' | 'antigravity'; instance: string }): Promise<UsageQuotaRefreshV1>;
+  };
+  openLobby(): Promise<void>;
+}
+export interface UsageTotalsV1 {
+  observations: number;
+  inputTokens: number | null;
+  outputTokens: number | null;
+  totalTokens: number | null;
+  costs: Array<{ currency: string; amount: number; observations: number }>;
+  confidence: { reported: number; aggregated: number; estimated: number; unknown: number };
+  lastObservedAt: string | null;
+}
+export interface UsageTargetV1 { provider: string; instance: string; backend: 'cli' | 'api' }
+export interface UsageGuardrailV1 {
+  provider: string | null; instance: string | null; backend: 'cli' | 'api' | null;
+  outcome: string; scope: string; sessionId: string | null; observedAt: string; cooldownUntil: string | null;
+}
+export interface UsageSnapshotV1 {
+  schemaVersion: 1; generatedAt: string; runtime: { status: 'available'; epoch: string };
+  coverage: { mode: 'memory'; scope: 'runtime_observed_results'; startedAt: string;
+    firstRetainedAt: string | null; lastObservedAt: string | null; retainedRecords: number; droppedRecords: number;
+    droppedQuotaTargets: number; targetCount: number; sessionCount: number; truncated: boolean; historyAvailable: false };
+  totals: UsageTotalsV1;
+  targets: Array<UsageTargetV1 & { usage: UsageTotalsV1; guardrails: UsageGuardrailV1[]; quota: {
+    status: 'available' | 'unavailable' | 'unsupported'; freshness: 'fresh' | 'stale' | 'unknown';
+    source: string | null; observedAt: string | null; accountId: null; accountLinkage: 'unverified';
+    scope: 'provider_reported_during_runtime_execution' | 'provider_account_query'; automaticRefresh: false;
+    limitId: string | null;
+    refreshSupported: boolean;
+    windows: Array<{ id: string; unit: 'percent' | 'requests' | 'credits'; used: number | null; limit: number | null; remaining: number | null; unlimited: boolean; usedPercent: number | null; remainingPercent: number | null; resetsAt: string | null; windowMinutes: number | null }>;
+  } }>;
+  sessions: Array<UsageTargetV1 & { sessionId: string; usage: UsageTotalsV1 }>;
+  incidents: Array<UsageTargetV1 & { id: string; classification: string; scope: string; observedAt: string; retryAt: string | null }>;
+  guardrails: UsageGuardrailV1[];
+}
+declare global { var catsApp: CatsAppBrowserSdkV1; }
+export interface UsageQuotaRefreshV1 {
+  status: 'updated' | 'cooldown' | 'busy' | 'auth_required' | 'unsupported' | 'unavailable' | 'timeout' | 'error';
+  nextRefreshAt: string | null;
+  snapshot: UsageSnapshotV1;
+}

package/packages/app-sdk/browser.js

@@ -0,0 +1,48 @@
+// Injected by the host before the app. No credentials or general HTTP proxy.
+(() => {
+  'use strict';
+  const boot = globalThis.__CATS_APP_BOOT__;
+  delete globalThis.__CATS_APP_BOOT__;
+  const pending = new Map();
+  let nextId = 0;
+  let port;
+  let resolveReady;
+  const ready = new Promise((resolve) => { resolveReady = resolve; });
+  const connect = (event) => {
+    if (event.source !== parent || event.data?.type !== 'cats.app.connect'
+      || event.data?.nonce !== boot.nonce || !event.ports[0] || port) return;
+    port = event.ports[0];
+    window.removeEventListener('message', connect);
+    port.onmessage = ({ data }) => {
+      const request = pending.get(data?.id);
+      if (!request) return;
+      pending.delete(data.id);
+      clearTimeout(request.timer);
+      if (data.ok) request.resolve(data.value);
+      else request.reject(new Error(data.error || 'App bridge request failed.'));
+    };
+    port.start();
+    resolveReady();
+  };
+  window.addEventListener('message', connect);
+  parent.postMessage({ type: 'cats.app.ready', nonce: boot.nonce }, '*');
+  const request = async (method, params) => {
+    await Promise.race([ready, new Promise((_, reject) => setTimeout(() => reject(new Error('App host is unavailable.')), 5000))]);
+    if (pending.size >= 4) throw new Error('Too many pending app requests.');
+    return new Promise((resolve, reject) => {
+      const id = ++nextId;
+      const timer = setTimeout(() => { pending.delete(id); reject(new Error('App bridge timed out.')); }, method === 'usage.refreshQuota' ? 15000 : 12000);
+      pending.set(id, { resolve, reject, timer });
+      port.postMessage({ id, method, params });
+    });
+  };
+  Object.defineProperty(globalThis, 'catsApp', { value: Object.freeze({
+    sdkVersion: '1.2.0', appId: boot.appId, version: boot.version,
+    locale: boot.locale, theme: boot.theme,
+    usage: Object.freeze({
+      getSnapshot: () => request('usage.snapshot'),
+      refreshQuota: (target) => request('usage.refreshQuota', target),
+    }),
+    openLobby: () => request('navigation.lobby'),
+  }), writable: false, configurable: false });
+})();

package/packages/app-sdk/package.d.ts

@@ -0,0 +1,14 @@
+export const APP_SDK_VERSION: string;
+export const PLATFORM_VERSION: string;
+export const MAX_PACKAGE_BYTES: number;
+export interface AppPin { id: string; version: string; sha256: string; artifact: string }
+export interface ResolvedAppPin extends AppPin { bytes: Buffer; manifest: Record<string, any> }
+export function sha256(bytes: Uint8Array): string;
+export function readBrowserSdk(): Promise<string>;
+export function supportsVersion(version: string, range: string): boolean;
+export function decodeAppPackage(bytes: Uint8Array, expected?: Pick<AppPin, 'id' | 'version' | 'sha256'>): {
+  manifest: Record<string, any>; files: { path: string; data: Buffer }[]; sha256: string;
+};
+export function parseAppLock(value: unknown): { schemaVersion: 1; apps: AppPin[] };
+export function resolveAppLock(lockPath: string): Promise<ResolvedAppPin[]>;
+export function materializeAppSelection(apps: ResolvedAppPin[]): Promise<string>;

package/packages/app-sdk/package.js

@@ -0,0 +1,131 @@
+import { createHash } from 'node:crypto';
+import { gunzipSync } from 'node:zlib';
+import { readFile, stat, mkdtemp, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { tmpdir } from 'node:os';
+import { createRequire } from 'node:module';
+
+export const APP_SDK_VERSION = '1.2.0';
+export const PLATFORM_VERSION = createRequire(import.meta.url)('../../package.json').version;
+export const MAX_PACKAGE_BYTES = 8 * 1024 * 1024;
+const MAX_EXPANDED_BYTES = 24 * 1024 * 1024;
+const ID = /^[a-z][a-z0-9]*(?:[.-][a-z0-9]+)*$/;
+const VERSION = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/;
+const HASH = /^[a-f0-9]{64}$/;
+const object = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+export const sha256 = (bytes) => createHash('sha256').update(bytes).digest('hex');
+export const readBrowserSdk = () => readFile(new URL('./browser.js', import.meta.url), 'utf8');
+
+// v1 deliberately supports exact versions, ^x.y.z, x.y.x and x.x only.
+// Reject rather than guess at unsupported semver expressions / prereleases.
+export function supportsVersion(version, range) {
+  if (typeof version !== 'string' || typeof range !== 'string' || !VERSION.test(version)) return false;
+  const v = version.split('.').map(Number);
+  if (VERSION.test(range)) return range === version;
+  const wildcard = /^(0|[1-9]\d*)\.(?:(0|[1-9]\d*)\.)?x$/.exec(range);
+  if (wildcard) return v[0] === Number(wildcard[1]) && (wildcard[2] === undefined || v[1] === Number(wildcard[2]));
+  if (!range.startsWith('^') || !VERSION.test(range.slice(1))) return false;
+  const r = range.slice(1).split('.').map(Number);
+  const compare = v[0] - r[0] || v[1] - r[1] || v[2] - r[2];
+  if (compare < 0 || v[0] !== r[0]) return false;
+  return r[0] > 0 || (v[1] === r[1] && (r[1] > 0 || v[2] === r[2]));
+}
+
+function assertIdentity(id, version) {
+  if (typeof id !== 'string' || id.length > 100 || !ID.test(id)
+    || typeof version !== 'string' || !VERSION.test(version)) throw new Error('Invalid app ID or stable version.');
+}
+
+export function decodeAppPackage(bytes, expected) {
+  if (bytes.length > MAX_PACKAGE_BYTES) throw new Error('App package exceeds compressed size limit.');
+  const digest = sha256(bytes);
+  if (expected && (!HASH.test(expected.sha256) || digest !== expected.sha256)) throw new Error('App package SHA-256 mismatch.');
+  const envelope = JSON.parse(gunzipSync(bytes, { maxOutputLength: MAX_EXPANDED_BYTES }).toString('utf8'));
+  if (!object(envelope) || envelope.schemaVersion !== 1 || envelope.kind !== 'cats-app'
+    || !object(envelope.manifest) || !Array.isArray(envelope.files)) throw new Error('Invalid Cats App v1 archive.');
+  const { manifest } = envelope;
+  assertIdentity(manifest.id, manifest.version);
+  if (expected && (manifest.id !== expected.id || manifest.version !== expected.version)) throw new Error('App package identity/version mismatch.');
+  if (envelope.files.length === 0 || envelope.files.length > 128) throw new Error('Invalid app file count.');
+  const seen = new Set();
+  const files = envelope.files.map((file) => {
+    // Portable, case-insensitive namespace. No symlinks, executable hooks, or device names.
+    if (!object(file) || typeof file.path !== 'string' || file.path.length > 180
+      || !/^[a-zA-Z0-9_./-]+$/.test(file.path)
+      || file.path.split('/').some((part) => !part || part === '.' || part === '..'
+        || /^(con|prn|aux|nul|com[0-9]|lpt[0-9])(?:\.|$)/i.test(part) || part.endsWith('.'))
+      || ['cats.app.json', '.package.json'].includes(file.path.toLowerCase())
+      || seen.has(file.path.toLowerCase()) || typeof file.base64 !== 'string'
+      || !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(file.base64)) {
+      throw new Error('Unsafe, duplicate, or invalid app file.');
+    }
+    seen.add(file.path.toLowerCase());
+    const data = Buffer.from(file.base64, 'base64');
+    if (data.length > 8 * 1024 * 1024 || data.toString('base64') !== file.base64) throw new Error('Invalid app file payload.');
+    return { path: file.path, data };
+  });
+  if (typeof manifest.entrypoints?.renderer !== 'string'
+    || !files.some((file) => file.path === manifest.entrypoints.renderer)
+    || !manifest.entrypoints.renderer.endsWith('.html')
+    || manifest.entrypoints.server || manifest.entrypoints.worker) throw new Error('v1 packages require a self-contained HTML renderer; server/worker execution is unsupported.');
+  return { manifest, files, sha256: digest };
+}
+
+export function parseAppLock(value) {
+  if (!object(value) || value.schemaVersion !== 1 || !Array.isArray(value.apps) || value.apps.length > 64) throw new Error('Invalid app bundle lock.');
+  const seen = new Set();
+  return { schemaVersion: 1, apps: value.apps.map((entry) => {
+    if (!object(entry)) throw new Error('Invalid app pin.');
+    assertIdentity(entry.id, entry.version);
+    if (seen.has(entry.id) || !HASH.test(entry.sha256) || typeof entry.artifact !== 'string' || !entry.artifact.trim()) throw new Error('Duplicate or incomplete app pin.');
+    seen.add(entry.id);
+    return { id: entry.id, version: entry.version, sha256: entry.sha256, artifact: entry.artifact };
+  }) };
+}
+
+export async function resolveAppLock(lockPath) {
+  const lock = parseAppLock(JSON.parse(await readFile(lockPath, 'utf8')));
+  const resolved = [];
+  for (const pin of lock.apps) {
+    let bytes;
+    if (/^https:/i.test(pin.artifact)) {
+      const url = new URL(pin.artifact);
+      const parts = url.pathname.split('/');
+      if (url.hostname !== 'github.com' || url.port || url.username || url.password || url.search || url.hash
+        || parts.length !== 7 || parts[3] !== 'releases' || parts[4] !== 'download'
+        || /latest|nightly|current/i.test(parts[5])) throw new Error('App URL must be a pinned GitHub release asset, not a moving alias.');
+      const response = await fetch(url, { signal: AbortSignal.timeout(60_000) });
+      if (!response.ok || !response.body) throw new Error(`Cannot download pinned app: HTTP ${response.status}.`);
+      const chunks = []; let size = 0;
+      for await (const chunk of response.body) {
+        size += chunk.length;
+        if (size > MAX_PACKAGE_BYTES) { await response.body.cancel().catch(() => {}); throw new Error('App download exceeds size limit.'); }
+        chunks.push(chunk);
+      }
+      bytes = Buffer.concat(chunks);
+    } else {
+      if (/^[a-z]+:\/\//i.test(pin.artifact)) throw new Error('Unsupported app artifact URL.');
+      const artifactPath = path.resolve(path.dirname(lockPath), pin.artifact);
+      if ((await stat(artifactPath)).size > MAX_PACKAGE_BYTES) throw new Error('App package exceeds size limit.');
+      bytes = await readFile(artifactPath);
+    }
+    const decoded = decodeAppPackage(bytes, pin);
+    resolved.push({ ...pin, bytes, manifest: decoded.manifest });
+  }
+  return resolved;
+}
+
+export async function materializeAppSelection(apps) {
+  parseAppLock({ schemaVersion: 1, apps });
+  for (const app of apps) decodeAppPackage(app.bytes, app);
+  const directory = await mkdtemp(path.join(tmpdir(), 'cats-desktop-apps-'));
+  const pins = [];
+  for (const app of apps) {
+    const artifact = `${app.id}-${app.version}.catsapp`;
+    await writeFile(path.join(directory, artifact), app.bytes, { flag: 'wx' });
+    pins.push({ id: app.id, version: app.version, sha256: app.sha256, artifact });
+  }
+  const lockPath = path.join(directory, 'bundle.lock.json');
+  await writeFile(lockPath, `${JSON.stringify({ schemaVersion: 1, apps: pins }, null, 2)}\n`, { flag: 'wx' });
+  return lockPath;
+}

package/packages/app-sdk/package.json

@@ -0,0 +1,7 @@
+{
+  "name": "@cats-inc/app-sdk",
+  "version": "1.2.0",
+  "private": true,
+  "type": "module",
+  "description": "Host-owned Cats App v1 package codec and injected browser SDK."
+}

package/scripts/README.md

@@ -143,7 +143,8 @@ discovery paths do not depend on bootstrap submodules:
 - `scripts/linux/sync-agent-skills.sh`
 - `scripts/macos/sync-agent-skills.sh`
 
-These scripts sync `skills/` into `.claude/skills` and `.agents/skills`, and
+These scripts recursively discover packages under developer `skills/` and copy
+their complete resources into `.claude/skills` and `.agents/skills`, and
 support:
 
 - `--clean` / `-Clean`
@@ -153,6 +154,10 @@ Antigravity CLI is intentionally not a skill sync target yet. Its repo/project
 skill discovery path has not been verified, so these helpers do not create an
 `.antigravity/skills` convention.
 
+Skill discovery stops at package roots and rejects duplicate leaf names before
+writing. It skips pending `*.bootstrap` directories. Desktop packaging obtains
+product skills separately from `cats-runtime/runtime-skills/`.
+
 ## Self-Hosted npm Package Helpers
 
 `cats-platform` now also ships repo-owned npm pack/install smoke helpers on
@@ -187,7 +192,7 @@ packaging and installer flows.
 - `scripts/windows/Install-Antigravity.ps1`
 - `scripts/windows/Install-Grok.ps1`
 - `scripts/windows/Install-Devin.ps1`
-- `scripts/windows/Install-Aider.ps1`
+- `scripts/windows/Install-MetaCli.ps1`
 - `scripts/windows/Install-Copilot.ps1`
 - `scripts/windows/Install-OpenCode.ps1`
 - `scripts/windows/Install-KiloCli.ps1`
@@ -253,28 +258,40 @@ still owed after a successful install: run `devin auth login` once and check
 with `devin auth status`. Uninstall removes the versioned tree under
 `%LOCALAPPDATA%\devin\cli` as well as the entry point.
 
-`Install-Aider.ps1` wraps Aider's installer, which is the uv installer plus
-`uv tool install --force --python python3.12 --with pip aider-chat@latest`. The
-entry point is a uv tool shim rather than the tool, so uninstall runs
-`uv tool uninstall aider-chat` before removing paths — deleting the shim alone
-leaves `aider-chat` installed and the shim regenerable. The uv binary Aider
-installs alongside it is deliberately left in place: users commonly have their
-own, and the helper cannot tell them apart.
-
-Cats installs and detects Devin and Aider but does not run sessions through
-either from the CLI backend. Devin has no machine-readable CLI output and
-executes through the `agent/acp` backend instead; Aider has no machine-readable
-output, no ACP or server mode, and exits 0 even when its model call fails.
-Neither appears in the product execution catalog.
-
-`Check-WindowsSetupReadiness.ps1` composes the repo-owned packaged setup
-helpers into one host-readable audit for the npm prefix substrate, the
-per-CLI npm-global helpers, the native Windows provider helpers including
-Kiro, and the optional local-model/Ollama follow-up. Set
-`CATS_DESKTOP_SETUP_AUDIT_PARALLEL=false` when you need the packaged host to
-force that audit into serial collection for debugging. WSL and Docker
-substrates were removed from the packaged path in earlier phases and are no
-longer covered here.
+`Install-MetaCli.ps1` and `install-meta-cli.sh` wrap Meta's Muse installer.
+What that installer places is a *launcher*, not the agent: it downloads
+`muse-bin-<version>` beside itself and records the version in `.muse-version`.
+Two things follow from that.
+
+Detection requires the agent build, not the entry point. The installer writes
+the shim and launcher first and downloads the agent last, so a run that fails in
+between leaves an entry point with nothing behind it; reporting that as
+installed would skip the reinstall that repairs it. Uninstall removes every
+`muse-bin-*` build and `.muse-*` state file in the install directory, not just
+the entry point.
+
+The version is read from `.muse-version` and the helpers never execute `muse`.
+The launcher forwards every argument straight to the agent binary, so a flag
+that binary does not recognise opens the interactive TUI instead of failing —
+in a packaged setup step with no console a prompt can reach, that is an
+unbounded hang rather than an error. On Windows the installer runs under
+Windows PowerShell 5.1 for the same reason the launcher does: a `PSModulePath`
+inherited from PowerShell 7 breaks the launcher's download step.
+
+Install directories differ by platform: `%LOCALAPPDATA%\Programs\muse` on Windows
+(entry point `muse.cmd`) and `~/.local/bin` on macOS and Linux. `MUSE_INSTALL_DIR`
+overrides both, matching the official installer.
+
+Cats installs and detects Devin but does not run its sessions through the CLI
+backend. Devin has no machine-readable CLI output and executes through the
+`agent/acp` backend instead, so it has no `cli/native` entry in the product
+execution catalog.
+
+`Check-WindowsSetupReadiness.ps1` remains an explicit operator utility for an
+aggregate audit. Packaged Desktop runs individual checks only for Runtime-selected
+native targets: shared Node/npm prerequisites and selected local Ollama. It does
+not invoke the aggregate audit during startup. WSL/Docker variants remain
+operator-configured and are outside the native Desktop helper editor.
 
 OpenClaw is intentionally not part of this local readiness audit because the
 provider catalog models it as an `agent/gateway` backend, not a repo-owned
@@ -296,7 +313,7 @@ runtime:
 - `scripts/linux/install-antigravity.sh`
 - `scripts/linux/install-grok.sh`
 - `scripts/linux/install-devin.sh`
-- `scripts/linux/install-aider.sh`
+- `scripts/linux/install-meta-cli.sh`
 - `scripts/linux/install-copilot.sh`
 - `scripts/linux/install-opencode.sh`
 - `scripts/linux/install-kilo.sh`
@@ -317,7 +334,7 @@ runtime:
 - `scripts/macos/install-antigravity.sh`
 - `scripts/macos/install-grok.sh`
 - `scripts/macos/install-devin.sh`
-- `scripts/macos/install-aider.sh`
+- `scripts/macos/install-meta-cli.sh`
 - `scripts/macos/install-copilot.sh`
 - `scripts/macos/install-opencode.sh`
 - `scripts/macos/install-kilo.sh`

package/scripts/build-desktop-installer.mjs

@@ -8,6 +8,7 @@ import { spawn } from 'node:child_process';
 
 import { parseStableReleaseTag } from './validate-release-version.mjs';
 import { DESCRIPTOR_RELATIVE_PATH } from './generate-desktop-release-descriptor.mjs';
+import { resolveAppLock, materializeAppSelection } from '#cats-app-package';
 
 const SCRIPT_PATH = fileURLToPath(import.meta.url);
 const PROJECT_ROOT = resolve(dirname(SCRIPT_PATH), '..');
@@ -32,6 +33,7 @@ Options:
   --format <nsis|dmg|pkg|zip|AppImage|deb|tar.gz>
                                          Override the configured installer formats.
   --sidecar-layout <split|bundle>         Choose loose-file or bundled sidecars for both app/runtime.
+  --apps-lock <path>                      Bundle the exact ID/version/SHA-256 selection in this lock.
   --skip-mobile                           Skip the mobile bundle (\`expo export\`). Also honored via
                                           CATS_SKIP_MOBILE=1 in the environment or .env.
   --release                               Build an official release package: embed the release
@@ -102,6 +104,7 @@ export function parseArgs(argv, env = process.env) {
   // cannot override anything in the GITHUB_ namespace, and a preview run is
   // dispatched from a branch, so the tag has to arrive as an explicit input.
   let tag = (env.CATS_DESKTOP_RELEASE_TAG ?? env.GITHUB_REF_NAME ?? '').trim();
+  let appsLock = env.CATS_DESKTOP_APPS_LOCK?.trim() || null;
 
   for (let index = 0; index < argv.length; index += 1) {
     const value = argv[index];
@@ -117,12 +120,18 @@ export function parseArgs(argv, env = process.env) {
         previewMode,
         publish,
         tag,
+        ...(appsLock ? { appsLock } : {}),
       };
     }
     if (value === '--release') {
       releaseMode = true;
       continue;
     }
+    if (value === '--apps-lock') {
+      appsLock = argv[++index];
+      if (!appsLock || appsLock.startsWith('--')) throw new Error('--apps-lock requires a path.');
+      continue;
+    }
     if (value === '--no-release') {
       releaseMode = false;
       continue;
@@ -187,6 +196,7 @@ export function parseArgs(argv, env = process.env) {
     previewMode,
     publish,
     tag,
+    ...(appsLock ? { appsLock } : {}),
   };
 }
 
@@ -673,6 +683,10 @@ async function main() {
   }
 
   const resolvedTarget = resolveBuilderTarget(parsed.target);
+  // Resolve once before builds can clear build/. Stage an offline immutable copy
+  // in an OS temporary directory so retries never redownload a moving asset.
+  const selectedApps = parsed.appsLock ? await resolveAppLock(resolve(parsed.appsLock)) : null;
+  const appLockForBuild = selectedApps ? await materializeAppSelection(selectedApps) : null;
   const envOptions = { releaseMode: parsed.releaseMode };
 
   if (parsed.releaseMode && parsed.previewMode) {
@@ -762,6 +776,7 @@ async function main() {
       resolvedTarget,
       '--sidecar-layout',
       parsed.sidecarLayout,
+      ...(appLockForBuild ? ['--apps-lock', appLockForBuild] : []),
     ],
     PROJECT_ROOT,
     sidecarBuildEnv,

package/scripts/build-test-ui.mjs

@@ -28,7 +28,7 @@ if (entryPoints.length === 0) {
 await build({
   entryPoints,
   bundle: true,
-  external: ['jsdom', 'typescript'],
+  external: ['jsdom', 'typescript', '#cats-app-package'],
   platform: 'node',
   format: 'esm',
   outbase: testsDir,

package/scripts/bundle-server.mjs

@@ -4,13 +4,26 @@ import { fileURLToPath } from 'node:url';
 
 const root = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 
-await build({
-  entryPoints: [resolve(root, 'build', 'server', 'index.js')],
-  bundle: true,
-  outfile: resolve(root, 'build', 'server-bundle', 'index.js'),
-  platform: 'node',
-  target: 'node22',
-  format: 'esm',
-  sourcemap: true,
-  packages: 'external',
-});
+export function bundleServer({
+  entryPoint = resolve(root, 'build', 'server', 'index.js'),
+  outfile = resolve(root, 'build', 'server-bundle', 'index.js'),
+} = {}) {
+  return build({
+    entryPoints: [entryPoint],
+    bundle: true,
+    outfile,
+    platform: 'node',
+    target: 'node22',
+    format: 'esm',
+    sourcemap: true,
+    packages: 'external',
+    // Package-import aliases are otherwise inlined despite packages: external.
+    // Keep the SDK's import.meta.url beside its shipped browser.js resource.
+    external: ['#cats-app-package'],
+  });
+}
+
+if (resolve(process.argv[1] ?? '') === fileURLToPath(import.meta.url)) {
+  if (process.argv.includes('--help')) console.log('Usage: node scripts/bundle-server.mjs (after npm run build:server)');
+  else await bundleServer();
+}