@cats-inc/cats-platform 0.1.21 → 0.3.4

package/package.json

@@ -1,10 +1,13 @@
 {
   "name": "@cats-inc/cats-platform",
-  "version": "0.1.21",
+  "version": "0.3.4",
   "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,8 @@
     "build/server",
     "build/desktop",
     "scripts",
+    "packages/app-sdk",
+    "packages/provider-setup",
     "config/provider-capability-bootstrap.yaml.example",
     ".env.example",
     "README.md",
@@ -89,7 +94,7 @@
     "@types/react-dom": "^18.3.0",
     "@vitejs/plugin-react": "^4.3.1",
     "electron": "^41.2.0",
-    "electron-builder": "^26.8.1",
+    "electron-builder": "^26.16.1",
     "esbuild": "^0.27.0",
     "jsdom": "^24.1.3",
     "png-to-ico": "^3.0.1",
@@ -126,12 +131,28 @@
     },
     "files": [
       "build/desktop/**/*",
+      "packages/app-sdk/**/*",
+      "packages/provider-setup/**/*",
       "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 +167,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"
@@ -231,8 +259,9 @@
       "icon": "icon.icns",
       "artifactName": "Cats-${version}-${arch}.${ext}",
       "category": "public.app-category.productivity",
-      "hardenedRuntime": false,
+      "hardenedRuntime": true,
       "gatekeeperAssess": false,
+      "notarize": false,
       "extendInfo": {
         "NSSpeechRecognitionUsageDescription": "Cats uses speech recognition for voice input in the chat composer.",
         "NSMicrophoneUsageDescription": "Cats uses the microphone for voice input in the chat composer."

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/packages/provider-setup/manager.d.ts

@@ -0,0 +1,79 @@
+export interface ProviderTarget {
+  provider: string;
+  backend: 'cli' | 'api' | 'local' | 'agent';
+  instance: string;
+  endpoint?: string;
+}
+export interface ProviderSelection {
+  state: 'missing' | 'invalid' | 'empty' | 'selected';
+  revision: string;
+  targets: ProviderTarget[];
+  nativeSetupTargets: ProviderTarget[];
+  diskChanged: boolean;
+  error: string | null;
+}
+export interface ProviderObservation extends ProviderTarget {
+  commandStatus: string;
+  available: boolean;
+  version?: string | null;
+  authStatus?: string;
+  observedAt: string;
+  configurationStatus: 'unchanged' | 'changed' | 'not_selected';
+  connectionStatus?: 'connected' | 'failed' | 'not_checked';
+  detail?: string;
+}
+export interface ProviderSetupHelper {
+  id: string;
+  available: boolean;
+  supported: boolean;
+  supportsApply: boolean;
+  supportsUpgrade: boolean;
+  supportsForce: boolean;
+  supportsUninstall: boolean;
+}
+export interface ProviderSetupOutcome {
+  source?: 'installer' | 'detection';
+  status: string | null;
+  summary: string;
+  manualSteps: string[];
+  warnings: string[];
+  plannedActions: string[];
+  runState: string;
+}
+export interface DesktopPrerequisite {
+  helperId: string;
+  checking: boolean;
+  result: ProviderSetupOutcome | null;
+}
+export interface ProviderManagerSnapshot {
+  runtime: {
+    bootstrapRequired?: boolean;
+    selection: ProviderSelection;
+    universe: Array<ProviderTarget & { familyLabel: string; binaryName: string;
+      install?: { auth?: { hint?: string; docsUrl?: string }; install?: { docsUrl?: string } } | null }>;
+    observations?: ProviderObservation[];
+    connections?: Array<ProviderTarget & { endpoint: string; editable: boolean; source?: string }>;
+    state?: { status?: string; error?: string | null } | null;
+  };
+  helpers: ProviderSetupHelper[];
+  platform: 'windows' | 'macos' | 'linux';
+  operations: Array<{ targets: ProviderTarget[]; stage: string }>;
+  outcomes: Record<string, ProviderSetupOutcome>;
+  prerequisites?: DesktopPrerequisite[];
+  preview?: { target: ProviderTarget; result: ProviderSetupOutcome; revision: string };
+}
+export interface ProviderManagerBridge {
+  runSetupHelper?(helperId: string, mode: 'check' | 'apply'):
+    Promise<{ state?: { lastAction: ProviderSetupOutcome | null } }>;
+  getProviderSetup(context?: 'onboarding' | 'settings'): Promise<ProviderManagerSnapshot>;
+  applyProviderSetup(input: { targets: ProviderTarget[]; expectedRevision: string;
+    detectAfter: boolean; reload?: boolean }): Promise<ProviderManagerSnapshot>;
+  runProviderSetup(input: { action: 'detect' | 'install' | 'upgrade' | 'repair' | 'uninstall' | 'preview_uninstall';
+    targets: ProviderTarget[]; expectedRevision: string }): Promise<ProviderManagerSnapshot>;
+}
+export function mountProviderManager(root: HTMLElement, bridge: ProviderManagerBridge, options?: {
+  context?: 'onboarding' | 'settings';
+  locale?: string;
+  onContinue?: () => void | Promise<void>;
+  onFeedback?: (message: string) => void;
+}): { refresh(): Promise<void>; destroy(): void };