Skip to content

armgit / Orkas

Public Imported from GitHub
0

Orkas is an open-source (MIT), local-first AI team for your desktop: a Commander turns your goal into to-dos and coordinates 16 built-in specialist agents plus Claude Code, Codex, OpenCode, OpenClaw and Hermes, with projects, scheduled automations and connectors. Free app for macOS & Windows; built-in models or your own keys.

Seed and gate marketplace installs

wyt4e390eb0d5c9
diff --git a/src/main/features/builtin_marketplace_startup.ts b/src/main/features/builtin_marketplace_startup.ts
new file mode 100644
index 00000000..d90faadc
--- /dev/null
+++ b/src/main/features/builtin_marketplace_startup.ts
@@ -0,0 +1,78 @@
+import * as users from './users';
+import * as builtinMarketplace from './builtin_marketplace';
+import { createLogger } from '../logger';
+import { maskId } from '../util/log-redact';
+import type { BuiltinMarketplaceSeedResult } from './builtin_marketplace';
+
+const log = createLogger('builtin-marketplace');
+
+let inFlightUid = '';
+let inFlight: Promise<BuiltinMarketplaceSeedResult | null> | null = null;
+
+export interface SeedBuiltinMarketplaceForActiveUserOptions {
+ reason: string;
+ shouldContinue?: () => boolean;
+ onChanged?: (result: BuiltinMarketplaceSeedResult) => void;
+}
+
+function _hasSeedChanges(result: BuiltinMarketplaceSeedResult): boolean {
+ return !!(
+ result.seeded_agents
+ || result.seeded_skills
+ || result.manifest_agents
+ || result.manifest_skills
+ );
+}
+
+function _activeUidOrNull(): string | null {
+ try {
+ return users.getActiveUserId();
+ } catch {
+ return null;
+ }
+}
+
+export async function seedBuiltinMarketplaceForActiveUser(
+ opts: SeedBuiltinMarketplaceForActiveUserOptions,
+): Promise<BuiltinMarketplaceSeedResult | null> {
+ const uid = _activeUidOrNull();
+ if (!uid) {
+ log.warn('skip builtin marketplace seed: no active user', { reason: opts.reason });
+ return null;
+ }
+
+ if (inFlight && inFlightUid === uid) return inFlight;
+
+ const shouldContinue = (): boolean => {
+ if (opts.shouldContinue && !opts.shouldContinue()) return false;
+ return _activeUidOrNull() === uid;
+ };
+
+ inFlightUid = uid;
+ inFlight = (async () => {
+ const result = await builtinMarketplace.seedBuiltinMarketplaceForUser(uid, { shouldContinue });
+ if (_hasSeedChanges(result)) {
+ log.info('seeded builtin marketplace for active user', {
+ reason: opts.reason,
+ uid: maskId(uid),
+ ...result,
+ });
+ opts.onChanged?.(result);
+ }
+ return result;
+ })().catch((err) => {
+ log.warn('builtin marketplace seed for active user failed', {
+ reason: opts.reason,
+ uid: maskId(uid),
+ error: (err as Error).message,
+ });
+ return null;
+ }).finally(() => {
+ if (inFlightUid === uid) {
+ inFlightUid = '';
+ inFlight = null;
+ }
+ });
+
+ return inFlight;
+}
diff --git a/src/main/features/marketplace.ts b/src/main/features/marketplace.ts
index 65055e5d..29846bd5 100644
--- a/src/main/features/marketplace.ts
+++ b/src/main/features/marketplace.ts
@@ -39,6 +39,7 @@
*/
import AdmZip from 'adm-zip';
+import { app } from 'electron';
import * as fs from 'node:fs';
import * as fsp from 'node:fs/promises';
import * as path from 'node:path';
@@ -47,6 +48,12 @@ import { sha256OfFile } from '../util/sha256';
import { marketplaceContentTreeHash } from '../util/marketplace-tree-hash';
import { logPathRef } from '../util/log-redact';
import { fetchWithRetry } from '../util/retry';
+import {
+ minAppVersionFrom,
+ normalizeMinAppVersion,
+ satisfiesMinAppVersion,
+ type MinAppVersionSource,
+} from '../util/app-version-compat';
import {
userSkillsDir,
@@ -140,6 +147,12 @@ export interface MarketplaceAgent {
default_install?: boolean | number;
is_open_source?: boolean | number;
status?: string;
+ min_app_version?: string;
+ minAppVersion?: string;
+ min_version?: string;
+ minVersion?: string;
+ min_pc_version?: string;
+ minPcVersion?: string;
}
export interface MarketplaceSkill {
@@ -156,6 +169,12 @@ export interface MarketplaceSkill {
default_install?: boolean | number;
is_open_source?: boolean | number;
status?: string;
+ min_app_version?: string;
+ minAppVersion?: string;
+ min_version?: string;
+ minVersion?: string;
+ min_pc_version?: string;
+ minPcVersion?: string;
}
export interface AgentDetail {
@@ -178,6 +197,7 @@ export interface AgentDetail {
default_install?: boolean;
is_open_source?: boolean;
status?: string;
+ min_app_version?: string;
}
export interface SkillDetail {
@@ -197,6 +217,7 @@ export interface SkillDetail {
default_install?: boolean;
is_open_source?: boolean;
status?: string;
+ min_app_version?: string;
}
// ── listing ───────────────────────────────────────────────────────────────
@@ -397,10 +418,39 @@ export async function listMarketplaceProjects(
// ── detail (cache-aware) ──────────────────────────────────────────────────
// Detail-page entry. Caller provides the list-row's freshness pair so we can short-circuit
// when cache is hot; we still fetch + repopulate cache on miss / stale.
-type MarketplaceFreshness = { version: string; published_at: number; updated_at?: number };
+type MarketplaceFreshness = {
+ version: string;
+ published_at: number;
+ updated_at?: number;
+} & MinAppVersionSource;
type MarketplaceInstallKind = 'agent' | 'skill';
type MarketplaceInstallOpts = { force?: boolean; name?: string };
+function _currentAppVersion(): string {
+ try { return app.getVersion(); } catch { return ''; }
+}
+
+function _normalizeMarketplaceMinAppVersion(...sources: Array<MinAppVersionSource | null | undefined>): string {
+ return minAppVersionFrom(...sources);
+}
+
+function _assertMarketplaceAppCompatible(kind: MarketplaceInstallKind, id: string, name: string | undefined, minAppVersion: string): void {
+ const min = normalizeMinAppVersion(minAppVersion);
+ if (!min) return;
+ const current = _currentAppVersion();
+ if (satisfiesMinAppVersion(current, min)) return;
+ throw new MarketplaceInstallError(
+ kind,
+ id,
+ name,
+ `requires Orkas >= ${min}; current ${current || 'unknown'}`,
+ );
+}
+
+function _isMarketplaceAppCompatible(minAppVersion: string): boolean {
+ return satisfiesMinAppVersion(_currentAppVersion(), minAppVersion);
+}
+
export class MarketplaceInstallError extends Error {
code = 'MARKETPLACE_INSTALL_FAILED';
marketplaceKind: MarketplaceInstallKind;
@@ -530,16 +580,18 @@ export async function getAgentDetail(
id: agentId, version: expect.version, category: '',
published_at: expect.published_at, updated_at: expect.updated_at,
agent_json: cached, agent_json_url: '', create_uid: '',
+ ...(_normalizeMarketplaceMinAppVersion(expect, cached) ? { min_app_version: _normalizeMarketplaceMinAppVersion(expect, cached) } : {}),
};
}
}
// Miss → fetch + repopulate.
- const data = await postJson<{ agent_json: Record<string, unknown>; version: string; category: string; published_at: number; updated_at?: number; agent_json_url: string; agent_skills_bundle_url?: string; create_uid: string; default_install?: boolean; is_open_source?: boolean; status?: string; state?: string }>(
+ const data = await postJson<{ agent_json: Record<string, unknown>; version: string; category: string; published_at: number; updated_at?: number; agent_json_url: string; agent_skills_bundle_url?: string; create_uid: string; default_install?: boolean; is_open_source?: boolean; status?: string; state?: string; min_app_version?: string; minAppVersion?: string }>(
'/marketplace/agents/detail', { id: agentId },
);
await writeAgentCache(agentId, data.agent_json, {
version: data.version, published_at: data.published_at, updated_at: data.updated_at,
});
+ const minAppVersion = _normalizeMarketplaceMinAppVersion(data, data.agent_json);
return {
id: agentId, version: data.version, category: data.category,
published_at: data.published_at, updated_at: data.updated_at,
@@ -547,6 +599,7 @@ export async function getAgentDetail(
agent_skills_bundle_url: data.agent_skills_bundle_url || '',
create_uid: data.create_uid || '', default_install: data.default_install === true,
is_open_source: data.is_open_source === true, status: data.status || data.state || '',
+ ...(minAppVersion ? { min_app_version: minAppVersion } : {}),
};
}
@@ -560,19 +613,22 @@ export async function getSkillDetail(
id: skillId, version: expect.version, category: '',
published_at: expect.published_at, updated_at: expect.updated_at,
cache_dir: getSkillCacheDir(skillId), bundle_url: '', create_uid: '',
+ ...(_normalizeMarketplaceMinAppVersion(expect) ? { min_app_version: _normalizeMarketplaceMinAppVersion(expect) } : {}),
};
}
// Miss → fetch + write.
- const meta = await postJson<{ bundle_url: string; version: string; category: string; published_at: number; updated_at?: number; create_uid: string; default_install?: boolean; is_open_source?: boolean; name?: string; status?: string; state?: string }>(
+ const meta = await postJson<{ bundle_url: string; version: string; category: string; published_at: number; updated_at?: number; create_uid: string; default_install?: boolean; is_open_source?: boolean; name?: string; status?: string; state?: string; min_app_version?: string; minAppVersion?: string }>(
'/marketplace/skills/bundle', { id: skillId },
);
await _fetchAndCacheSkill(skillId, meta);
+ const minAppVersion = _normalizeMarketplaceMinAppVersion(meta);
return {
id: skillId, name: meta.name || '', version: meta.version, category: meta.category,
published_at: meta.published_at, updated_at: meta.updated_at,
cache_dir: getSkillCacheDir(skillId), bundle_url: meta.bundle_url,
create_uid: meta.create_uid || '', default_install: meta.default_install === true,
is_open_source: meta.is_open_source === true, status: meta.status || meta.state || '',
+ ...(minAppVersion ? { min_app_version: minAppVersion } : {}),
};
}
@@ -676,9 +732,10 @@ async function _installMarketplaceAgentLocked(
if (!detail.agent_json_url) {
// Cache-hit path returns url='' (and create_uid=''); re-fetch via detail endpoint to
// capture both — needed for manifest + `_install.json` author badge.
- const fresh = await postJson<{ agent_json: Record<string, unknown>; version: string; category: string; published_at: number; updated_at?: number; agent_json_url: string; agent_skills_bundle_url?: string; create_uid: string; default_install?: boolean; is_open_source?: boolean; status?: string; state?: string }>(
+ const fresh = await postJson<{ agent_json: Record<string, unknown>; version: string; category: string; published_at: number; updated_at?: number; agent_json_url: string; agent_skills_bundle_url?: string; create_uid: string; default_install?: boolean; is_open_source?: boolean; status?: string; state?: string; min_app_version?: string; minAppVersion?: string }>(
'/marketplace/agents/detail', { id: agentId },
);
+ const minAppVersion = _normalizeMarketplaceMinAppVersion(fresh, fresh.agent_json);
detail = {
id: agentId, version: fresh.version, category: fresh.category,
published_at: fresh.published_at, updated_at: fresh.updated_at,
@@ -688,9 +745,11 @@ async function _installMarketplaceAgentLocked(
default_install: fresh.default_install === true,
is_open_source: fresh.is_open_source === true,
status: fresh.status || fresh.state || '',
+ ...(minAppVersion ? { min_app_version: minAppVersion } : {}),
};
agentName = agentName || _agentJsonName(detail.agent_json);
}
+ _assertMarketplaceAppCompatible('agent', agentId, agentName, detail.min_app_version || '');
// 1. Install dependent skills FIRST, in parallel. Any failure throws — the agent body
// and manifest entry are never touched, so retry is a clean re-run (previously-installed
@@ -709,7 +768,7 @@ async function _installMarketplaceAgentLocked(
try {
// Direct hit on /skills/bundle for meta — avoids paging /skills/list (O(catalog) lookup
// that breaks once the catalog grows past 500 skills).
- const meta = await postJson<{ bundle_url: string; version: string; category: string; published_at: number; updated_at?: number; name?: string; status?: string; state?: string }>(
+ const meta = await postJson<{ bundle_url: string; version: string; category: string; published_at: number; updated_at?: number; name?: string; status?: string; state?: string; min_app_version?: string; minAppVersion?: string }>(
'/marketplace/skills/bundle', { id: sid },
);
depSkillName = meta.name || depSkillName;
@@ -718,6 +777,7 @@ async function _installMarketplaceAgentLocked(
version: meta.version,
published_at: meta.published_at,
updated_at: meta.updated_at,
+ ...(_normalizeMarketplaceMinAppVersion(meta) ? { min_app_version: _normalizeMarketplaceMinAppVersion(meta) } : {}),
}, { force: opts.force === true, name: depSkillName });
log.info(` dep-installed skill ${sid}`);
} catch (err) {
@@ -773,6 +833,7 @@ async function _installMarketplaceAgentLocked(
...(typeof detail.default_install === 'boolean' ? { default_install: detail.default_install } : {}),
...(typeof detail.is_open_source === 'boolean' ? { is_open_source: detail.is_open_source } : {}),
...(detail.status ? { status: detail.status } : {}),
+ ...(detail.min_app_version ? { min_app_version: detail.min_app_version } : {}),
...(installContentSha ? { content_sha: installContentSha } : {}),
...(installTreeHash ? { content_tree_hash: installTreeHash } : {}),
}, null, 2), 'utf8');
@@ -787,6 +848,7 @@ async function _installMarketplaceAgentLocked(
installed_at: installedAt,
...(typeof detail.default_install === 'boolean' ? { default_install: detail.default_install } : {}),
...(detail.status ? { status: detail.status } : {}),
+ min_app_version: detail.min_app_version || '',
});
invalidateCoreAgentSkills();
log.info('installed marketplace agent', { agentId, version: detail.version, target: logPathRef(target) });
@@ -818,10 +880,11 @@ async function _installMarketplaceSkillLocked(
let detail = await getSkillDetail(skillId, expect);
skillName = skillName || detail.name || '';
if (!detail.bundle_url) {
- const fresh = await postJson<{ bundle_url: string; version: string; category: string; published_at: number; updated_at?: number; create_uid: string; default_install?: boolean; is_open_source?: boolean; name?: string; status?: string; state?: string }>(
+ const fresh = await postJson<{ bundle_url: string; version: string; category: string; published_at: number; updated_at?: number; create_uid: string; default_install?: boolean; is_open_source?: boolean; name?: string; status?: string; state?: string; min_app_version?: string; minAppVersion?: string }>(
'/marketplace/skills/bundle', { id: skillId },
);
skillName = skillName || fresh.name || '';
+ const minAppVersion = _normalizeMarketplaceMinAppVersion(fresh);
detail = {
...detail,
name: fresh.name || detail.name,
@@ -832,8 +895,10 @@ async function _installMarketplaceSkillLocked(
default_install: fresh.default_install === true,
is_open_source: fresh.is_open_source === true,
status: fresh.status || fresh.state || '',
+ ...(minAppVersion ? { min_app_version: minAppVersion } : {}),
};
}
+ _assertMarketplaceAppCompatible('skill', skillId, skillName, detail.min_app_version || '');
const cacheDir = getSkillCacheDir(skillId);
const uid = getActiveUserId();
@@ -871,6 +936,7 @@ async function _installMarketplaceSkillLocked(
...(typeof detail.default_install === 'boolean' ? { default_install: detail.default_install } : {}),
...(typeof detail.is_open_source === 'boolean' ? { is_open_source: detail.is_open_source } : {}),
...(detail.status ? { status: detail.status } : {}),
+ ...(detail.min_app_version ? { min_app_version: detail.min_app_version } : {}),
...(skillContentSha ? { content_sha: skillContentSha } : {}),
...(skillTreeHash ? { content_tree_hash: skillTreeHash } : {}),
}, null, 2), 'utf8');
@@ -884,6 +950,7 @@ async function _installMarketplaceSkillLocked(
installed_at: installedAt,
...(typeof detail.default_install === 'boolean' ? { default_install: detail.default_install } : {}),
...(detail.status ? { status: detail.status } : {}),
+ min_app_version: detail.min_app_version || '',
});
log.info('installed marketplace skill', { skillId, version: detail.version, target: logPathRef(target) });
return { ok: true, id: skillId };
@@ -967,10 +1034,14 @@ async function _seedAgentSkillDependencies(
return { seeded, blocked: true };
}
try {
- const meta = await postJson<{ bundle_url: string; version: string; published_at: number; updated_at?: number; create_uid?: string; default_install?: boolean; status?: string; state?: string; name?: string }>(
+ const meta = await postJson<{ bundle_url: string; version: string; published_at: number; updated_at?: number; create_uid?: string; default_install?: boolean; status?: string; state?: string; name?: string; min_app_version?: string; minAppVersion?: string }>(
'/marketplace/skills/bundle', { id: sid },
);
_assertApprovedDependencySkill(sid, meta.name || sid, meta);
+ const minAppVersion = _normalizeMarketplaceMinAppVersion(meta);
+ if (!_isMarketplaceAppCompatible(minAppVersion)) {
+ throw new Error(`requires Orkas >= ${minAppVersion}; current ${_currentAppVersion() || 'unknown'}`);
+ }
if (!shouldContinue()) return { seeded, blocked: true };
await addSkillInstall(uid, {
id: sid,
@@ -981,6 +1052,7 @@ async function _seedAgentSkillDependencies(
create_uid: meta.create_uid || '',
...((meta.status || meta.state) ? { status: meta.status || meta.state } : {}),
default_install: meta.default_install === true,
+ ...(minAppVersion ? { min_app_version: minAppVersion } : {}),
});
seeded++;
installedSkills.add(sid);
@@ -1118,8 +1190,8 @@ export async function ensureDefaultInstalls(
return { seeded_agents: 0, seeded_skills: 0, skipped: true };
}
const data = await postJson<{
- agents: { id: string; version: string; published_at: number; updated_at?: number; agent_json_url: string; agent_skills_bundle_url?: string; create_uid?: string; status?: string; state?: string }[];
- skills: { id: string; version: string; published_at: number; updated_at?: number; bundle_url: string; create_uid?: string; status?: string; state?: string }[];
+ agents: { id: string; version: string; published_at: number; updated_at?: number; agent_json_url: string; agent_skills_bundle_url?: string; create_uid?: string; status?: string; state?: string; min_app_version?: string; minAppVersion?: string }[];
+ skills: { id: string; version: string; published_at: number; updated_at?: number; bundle_url: string; create_uid?: string; status?: string; state?: string; min_app_version?: string; minAppVersion?: string }[];
}>('/marketplace/defaults', {});
if (!canContinue()) return { seeded_agents: 0, seeded_skills: 0 };
const manifest = await readInstalls(uid);
@@ -1134,6 +1206,11 @@ export async function ensureDefaultInstalls(
if (!a || !a.id) continue;
if (deletedAgents.has(a.id)) continue;
try {
+ const minAppVersion = _normalizeMarketplaceMinAppVersion(a);
+ if (!_isMarketplaceAppCompatible(minAppVersion)) {
+ log.info(`skip default agent ${a.id}; requires Orkas >= ${minAppVersion}`);
+ continue;
+ }
const depSeed = await _seedAgentSkillDependencies(uid, a.id, installedSkills, deletedSkills, canContinue);
if (!canContinue()) return { seeded_agents: seededAgents, seeded_skills: seededSkills };
seededSkills += depSeed.seeded;
@@ -1147,6 +1224,7 @@ export async function ensureDefaultInstalls(
create_uid: a.create_uid || '',
...((a.status || a.state) ? { status: a.status || a.state } : {}),
default_install: true,
+ ...(minAppVersion ? { min_app_version: minAppVersion } : {}),
});
seededAgents++;
installedAgents.add(a.id);
@@ -1159,6 +1237,11 @@ export async function ensureDefaultInstalls(
if (!s || !s.id) continue;
if (installedSkills.has(s.id) || deletedSkills.has(s.id)) continue;
try {
+ const minAppVersion = _normalizeMarketplaceMinAppVersion(s);
+ if (!_isMarketplaceAppCompatible(minAppVersion)) {
+ log.info(`skip default skill ${s.id}; requires Orkas >= ${minAppVersion}`);
+ continue;
+ }
await addSkillInstall(uid, {
id: s.id, version: s.version || '1.0.0',
published_at: s.published_at || 0,
@@ -1167,6 +1250,7 @@ export async function ensureDefaultInstalls(
create_uid: s.create_uid || '',
...((s.status || s.state) ? { status: s.status || s.state } : {}),
default_install: true,
+ ...(minAppVersion ? { min_app_version: minAppVersion } : {}),
});
seededSkills++;
installedSkills.add(s.id);
@@ -1183,8 +1267,12 @@ export async function ensureDefaultInstalls(
seeded_at: Date.now(),
checked_at: Date.now(),
version: 1,
- agent_ids: (data.agents || []).map((a) => a.id),
- skill_ids: (data.skills || []).map((s) => s.id),
+ agent_ids: (data.agents || [])
+ .filter((a) => _isMarketplaceAppCompatible(_normalizeMarketplaceMinAppVersion(a)))
+ .map((a) => a.id),
+ skill_ids: (data.skills || [])
+ .filter((s) => _isMarketplaceAppCompatible(_normalizeMarketplaceMinAppVersion(s)))
+ .map((s) => s.id),
}, null, 2), 'utf8');
log.info(`seeded default installs: ${seededAgents} agent(s) + ${seededSkills} skill(s)`);
return { seeded_agents: seededAgents, seeded_skills: seededSkills };
diff --git a/src/main/features/marketplace_installs.ts b/src/main/features/marketplace_installs.ts
index fd721f7e..48d893f3 100644
--- a/src/main/features/marketplace_installs.ts
+++ b/src/main/features/marketplace_installs.ts
@@ -51,6 +51,7 @@ import { Mutex } from 'async-mutex';
import { userMarketplaceInstallsFile, userMarketplaceDirCloud } from '../paths';
import { createLogger } from '../logger';
import { isExpiredMsTombstone } from '../util/tombstone_retention';
+import { minAppVersionFrom, type MinAppVersionSource } from '../util/app-version-compat';
const log = createLogger('marketplace_installs');
@@ -105,6 +106,8 @@ export interface AgentInstall {
* These rows may start without server URLs; online resolution patches them
* into ordinary marketplace rows. */
seed_source?: 'builtin' | string;
+ /** Minimum Orkas app version required to materialize/run this marketplace agent. */
+ min_app_version?: string;
}
export interface SkillInstall {
@@ -125,6 +128,8 @@ export interface SkillInstall {
state?: string;
/** Same as `AgentInstall.seed_source`. */
seed_source?: 'builtin' | string;
+ /** Minimum Orkas app version required to materialize/run this marketplace skill. */
+ min_app_version?: string;
}
export const CURRENT_VERSION = 1;
@@ -195,12 +200,12 @@ export async function addAgentInstall(uid: string, row: Omit<AgentInstall, 'inst
const manifest = await readInstalls(uid);
const idx = manifest.agents.findIndex((a) => a.id === row.id);
const previous = idx >= 0 ? manifest.agents[idx] : null;
- const entry: AgentInstall = {
+ const entry: AgentInstall = _normalizeAgentRow({
...(previous || {}),
...row,
version: normalizeInstallVersion(row.version || previous?.version),
installed_at: row.installed_at || previous?.installed_at || Date.now(),
- };
+ } as AgentInstall & MinAppVersionSource);
if (idx >= 0) manifest.agents[idx] = entry;
else manifest.agents.push(entry);
delete manifest._deleted_at?.agents?.[row.id];
@@ -215,12 +220,12 @@ export async function addSkillInstall(uid: string, row: Omit<SkillInstall, 'inst
const manifest = await readInstalls(uid);
const idx = manifest.skills.findIndex((s) => s.id === row.id);
const previous = idx >= 0 ? manifest.skills[idx] : null;
- const entry: SkillInstall = {
+ const entry: SkillInstall = _normalizeSkillRow({
...(previous || {}),
...row,
version: normalizeInstallVersion(row.version || previous?.version),
installed_at: row.installed_at || previous?.installed_at || Date.now(),
- };
+ } as SkillInstall & MinAppVersionSource);
if (idx >= 0) manifest.skills[idx] = entry;
else manifest.skills.push(entry);
delete manifest._deleted_at?.skills?.[row.id];
@@ -283,12 +288,36 @@ function _isSkillRow(x: unknown): x is SkillInstall {
&& typeof r.installed_at === 'number';
}
-function _normalizeAgentRow(row: AgentInstall): AgentInstall {
- return { ...row, version: normalizeInstallVersion(row.version) };
+function _normalizeAgentRow(row: AgentInstall & MinAppVersionSource): AgentInstall {
+ const rest = { ...(row as AgentInstall & MinAppVersionSource & Record<string, unknown>) };
+ delete rest.min_app_version;
+ delete rest.minAppVersion;
+ delete rest.min_version;
+ delete rest.minVersion;
+ delete rest.min_pc_version;
+ delete rest.minPcVersion;
+ const minAppVersion = minAppVersionFrom(row);
+ return {
+ ...rest,
+ version: normalizeInstallVersion(row.version),
+ ...(minAppVersion ? { min_app_version: minAppVersion } : {}),
+ };
}
-function _normalizeSkillRow(row: SkillInstall): SkillInstall {
- return { ...row, version: normalizeInstallVersion(row.version) };
+function _normalizeSkillRow(row: SkillInstall & MinAppVersionSource): SkillInstall {
+ const rest = { ...(row as SkillInstall & MinAppVersionSource & Record<string, unknown>) };
+ delete rest.min_app_version;
+ delete rest.minAppVersion;
+ delete rest.min_version;
+ delete rest.minVersion;
+ delete rest.min_pc_version;
+ delete rest.minPcVersion;
+ const minAppVersion = minAppVersionFrom(row);
+ return {
+ ...rest,
+ version: normalizeInstallVersion(row.version),
+ ...(minAppVersion ? { min_app_version: minAppVersion } : {}),
+ };
}
function _readDeletedAt(parsed: Partial<InstallsManifest> & { version?: unknown }): InstallsManifest['_deleted_at'] | null {
diff --git a/src/main/features/marketplace_reconcile.ts b/src/main/features/marketplace_reconcile.ts
index 78684cf9..50b309fb 100644
--- a/src/main/features/marketplace_reconcile.ts
+++ b/src/main/features/marketplace_reconcile.ts
@@ -17,6 +17,8 @@ import * as fs from 'node:fs';
import * as fsp from 'node:fs/promises';
import * as path from 'node:path';
+import { app } from 'electron';
+
import {
userMarketplaceAgentDir, userMarketplaceAgentSkillsDir, userMarketplaceSkillDir,
userMarketplaceAgentsDir, userMarketplaceSkillsDir,
@@ -40,11 +42,35 @@ import { extractBundleSafely, postJson } from './marketplace';
import { withMarketplaceInstallLock } from './marketplace_locks';
import { createLogger } from '../logger';
import { fetchWithRetry } from '../util/retry';
+import {
+ minAppVersionFrom,
+ satisfiesMinAppVersion,
+ type MinAppVersionSource,
+} from '../util/app-version-compat';
const log = createLogger('marketplace_reconcile');
const MARKETPLACE_AGENT_JSON_DOWNLOAD_TIMEOUT_MS = 60_000;
const MARKETPLACE_SKILL_BUNDLE_DOWNLOAD_TIMEOUT_MS = 10 * 60 * 1000;
+function _currentAppVersion(): string {
+ try { return app.getVersion(); } catch { return ''; }
+}
+
+function _normalizeMinAppVersion(...sources: Array<MinAppVersionSource | null | undefined>): string {
+ return minAppVersionFrom(...sources);
+}
+
+function _isAppCompatible(minAppVersion: string): boolean {
+ return satisfiesMinAppVersion(_currentAppVersion(), minAppVersion);
+}
+
+function _isInstallRowAppCompatible(row: ({ id?: string } & MinAppVersionSource), kind: 'agent' | 'skill'): boolean {
+ const min = minAppVersionFrom(row);
+ if (!min || _isAppCompatible(min)) return true;
+ log.info(`skip ${kind} ${row.id || ''}; requires Orkas >= ${min} (current ${_currentAppVersion() || 'unknown'})`);
+ return false;
+}
+
/** Coarse-grained reconcile state for the UI banner. `idle` covers both pre-run and a finished
* run with nothing to pull (banner stays hidden in both cases). */
export type ReconcileState = 'idle' | 'running' | 'done';
@@ -220,6 +246,9 @@ export async function checkServerUpdatesForInstalls(
}
continue;
}
+ if (!_isInstallRowAppCompatible({ id: a.id, min_app_version: server.min_app_version }, 'agent')) {
+ continue;
+ }
const contentChanged = server.version !== a.version || _freshnessAt(server) !== _freshnessAt(a);
const defaultInstallChanged = typeof server.default_install === 'boolean'
&& a.default_install !== server.default_install;
@@ -227,7 +256,9 @@ export async function checkServerUpdatesForInstalls(
const statusChanged = typeof server.status === 'string' && currentStatus !== server.status;
const privateSkillsUrlChanged = typeof server.agent_skills_bundle_url === 'string'
&& a.agent_skills_bundle_url !== server.agent_skills_bundle_url;
- if (contentChanged || defaultInstallChanged || statusChanged || privateSkillsUrlChanged) {
+ const minAppVersionChanged = typeof server.min_app_version === 'string'
+ && a.min_app_version !== server.min_app_version;
+ if (contentChanged || defaultInstallChanged || statusChanged || privateSkillsUrlChanged || minAppVersionChanged) {
log.info(`server-update agent ${a.id}: v${a.version} → v${server.version} (freshness ${_freshnessAt(a)} → ${_freshnessAt(server)})`);
try { _assertContinue(opts); } catch { return { updated_agents, updated_skills }; }
// Replace the row in the manifest; reconcile will detect the version/freshness
@@ -241,12 +272,14 @@ export async function checkServerUpdatesForInstalls(
: (typeof a.agent_skills_bundle_url === 'string' ? { agent_skills_bundle_url: a.agent_skills_bundle_url } : {})),
...(typeof server.default_install === 'boolean' ? { default_install: server.default_install } : {}),
...(typeof server.status === 'string' ? { status: server.status } : {}),
+ ...(typeof server.min_app_version === 'string' ? { min_app_version: server.min_app_version } : {}),
});
- if (!contentChanged && !privateSkillsUrlChanged && (defaultInstallChanged || statusChanged)) {
+ if (!contentChanged && !privateSkillsUrlChanged && (defaultInstallChanged || statusChanged || minAppVersionChanged)) {
await withMarketplaceInstallLock(uid, 'agent', a.id, async () => {
await _patchInstallMeta(userMarketplaceAgentDir(uid, a.id), {
...(typeof server.default_install === 'boolean' ? { default_install: server.default_install } : {}),
...(typeof server.status === 'string' ? { status: server.status } : {}),
+ ...(typeof server.min_app_version === 'string' ? { min_app_version: server.min_app_version } : {}),
});
});
}
@@ -262,12 +295,17 @@ export async function checkServerUpdatesForInstalls(
}
continue;
}
+ if (!_isInstallRowAppCompatible({ id: s.id, min_app_version: server.min_app_version }, 'skill')) {
+ continue;
+ }
const contentChanged = server.version !== s.version || _freshnessAt(server) !== _freshnessAt(s);
const defaultInstallChanged = typeof server.default_install === 'boolean'
&& s.default_install !== server.default_install;
const currentStatus = s.status || s.state;
const statusChanged = typeof server.status === 'string' && currentStatus !== server.status;
- if (contentChanged || defaultInstallChanged || statusChanged) {
+ const minAppVersionChanged = typeof server.min_app_version === 'string'
+ && s.min_app_version !== server.min_app_version;
+ if (contentChanged || defaultInstallChanged || statusChanged || minAppVersionChanged) {
log.info(`server-update skill ${s.id}: v${s.version} → v${server.version} (freshness ${_freshnessAt(s)} → ${_freshnessAt(server)})`);
try { _assertContinue(opts); } catch { return { updated_agents, updated_skills }; }
await addSkillInstall(uid, {
@@ -275,12 +313,14 @@ export async function checkServerUpdatesForInstalls(
updated_at: server.updated_at, bundle_url: s.bundle_url, create_uid: s.create_uid,
...(typeof server.default_install === 'boolean' ? { default_install: server.default_install } : {}),
...(typeof server.status === 'string' ? { status: server.status } : {}),
+ ...(typeof server.min_app_version === 'string' ? { min_app_version: server.min_app_version } : {}),
});
- if (!contentChanged && (defaultInstallChanged || statusChanged)) {
+ if (!contentChanged && (defaultInstallChanged || statusChanged || minAppVersionChanged)) {
await withMarketplaceInstallLock(uid, 'skill', s.id, async () => {
await _patchInstallMeta(userMarketplaceSkillDir(uid, s.id), {
...(typeof server.default_install === 'boolean' ? { default_install: server.default_install } : {}),
...(typeof server.status === 'string' ? { status: server.status } : {}),
+ ...(typeof server.min_app_version === 'string' ? { min_app_version: server.min_app_version } : {}),
});
});
}
@@ -339,6 +379,7 @@ interface _CatalogRow {
default_install?: boolean;
status?: string;
agent_skills_bundle_url?: string;
+ min_app_version?: string;
}
/** Paginate the public `/marketplace/{kind}/list` endpoint and collapse to (id → version + ts).
@@ -350,7 +391,7 @@ async function _fetchServerCatalogMap(kind: 'agents' | 'skills', ids: string[]):
const PAGE_SIZE = 100;
const wanted = new Set(ids.filter(Boolean));
for (let page = 1; page <= 20; page++) {
- const r = await postJson<{ list: Array<{ id?: string; version?: string; published_at?: number; updated_at?: number; default_install?: boolean | number; status?: string; state?: string; agent_skills_bundle_url?: string }>; total?: number }>(
+ const r = await postJson<{ list: Array<{ id?: string; version?: string; published_at?: number; updated_at?: number; default_install?: boolean | number; status?: string; state?: string; agent_skills_bundle_url?: string; min_app_version?: string; minAppVersion?: string }>; total?: number }>(
`/marketplace/${kind}/list`, { page, size: PAGE_SIZE, ids: [...wanted] },
);
const list = r.list || [];
@@ -370,6 +411,7 @@ async function _fetchServerCatalogMap(kind: 'agents' | 'skills', ids: string[]):
...(kind === 'agents' && typeof row.agent_skills_bundle_url === 'string'
? { agent_skills_bundle_url: row.agent_skills_bundle_url }
: {}),
+ ...(_normalizeMinAppVersion(row) ? { min_app_version: _normalizeMinAppVersion(row) } : {}),
});
}
}
@@ -404,8 +446,8 @@ export async function reconcileInstalls(
}
// Filter pull-needed up front so the banner's total is meaningful (it counts work the user
// will actually see, not entries that short-circuit).
- const agentsNeedingPull = manifest.agents.filter((r) => _agentNeedsPull(uid, r));
- const skillsNeedingPull = manifest.skills.filter((r) => _skillNeedsPull(uid, r));
+ const agentsNeedingPull = manifest.agents.filter((r) => _isInstallRowAppCompatible(r, 'agent') && _agentNeedsPull(uid, r));
+ const skillsNeedingPull = manifest.skills.filter((r) => _isInstallRowAppCompatible(r, 'skill') && _skillNeedsPull(uid, r));
const agentPullIds = new Set(agentsNeedingPull.map((r) => r.id));
const skillPullIds = new Set(skillsNeedingPull.map((r) => r.id));
let metadataPatches: MetadataPatchCounts;
@@ -590,6 +632,7 @@ async function _reconcileLocalOnlyInstalls(
create_uid: meta.create_uid || '',
...(typeof meta.default_install === 'boolean' ? { default_install: meta.default_install } : {}),
...(meta.status ? { status: meta.status } : {}),
+ ...(meta.min_app_version ? { min_app_version: meta.min_app_version } : {}),
});
counts.restored_agents++;
log.info(`restored local-only marketplace agent ${id} into installs manifest`);
@@ -620,6 +663,7 @@ async function _reconcileLocalOnlyInstalls(
create_uid: meta.create_uid || '',
...(typeof meta.default_install === 'boolean' ? { default_install: meta.default_install } : {}),
...(meta.status ? { status: meta.status } : {}),
+ ...(meta.min_app_version ? { min_app_version: meta.min_app_version } : {}),
});
counts.restored_skills++;
log.info(`restored local-only marketplace skill ${id} into installs manifest`);
@@ -638,6 +682,7 @@ async function _patchLocalMetadataForManifest(
const counts: MetadataPatchCounts = { patched_agents: 0, patched_skills: 0 };
for (const row of manifest.agents) {
_assertContinue(opts);
+ if (!_isInstallRowAppCompatible(row, 'agent')) continue;
if (agentPullIds.has(row.id) || !_agentContentExists(uid, row.id)) continue;
const dir = userMarketplaceAgentDir(uid, row.id);
if (_resourceSyncBlocksServerPull(dir)) continue;
@@ -653,6 +698,7 @@ async function _patchLocalMetadataForManifest(
}
for (const row of manifest.skills) {
_assertContinue(opts);
+ if (!_isInstallRowAppCompatible(row, 'skill')) continue;
if (skillPullIds.has(row.id) || !_skillContentExists(uid, row.id)) continue;
const dir = userMarketplaceSkillDir(uid, row.id);
if (_resourceSyncBlocksServerPull(dir)) continue;
@@ -821,8 +867,14 @@ async function _ensureAgentSkillDependencies(
default_install?: boolean;
status?: string;
state?: string;
+ min_app_version?: string;
+ minAppVersion?: string;
}>('/marketplace/skills/bundle', { id: skillId });
_assertApprovedDependencySkill(skillId, meta);
+ const minAppVersion = _normalizeMinAppVersion(meta);
+ if (!_isAppCompatible(minAppVersion)) {
+ throw new Error(`dependency skill ${skillId} requires Orkas >= ${minAppVersion} (current ${_currentAppVersion() || 'unknown'})`);
+ }
row = {
id: skillId,
version: meta.version || '1.0.0',
@@ -833,6 +885,7 @@ async function _ensureAgentSkillDependencies(
create_uid: meta.create_uid || '',
...(typeof meta.default_install === 'boolean' ? { default_install: meta.default_install } : {}),
...((meta.status || meta.state) ? { status: meta.status || meta.state } : {}),
+ ...(minAppVersion ? { min_app_version: minAppVersion } : {}),
};
await addSkillInstall(uid, row);
manifestSkills.set(skillId, row);
@@ -914,6 +967,7 @@ interface InstallMeta {
is_open_source?: boolean;
status?: string;
state?: string;
+ min_app_version?: string;
seed_source?: string;
/** sha256 (hex) of the spec's descriptive file at install / upload time —
* agent.json for agents, SKILL.md for skills. Used only by the dev-mode
@@ -966,6 +1020,7 @@ function _installMetaFromAgentRow(row: AgentInstall): Partial<InstallMeta> {
create_uid: row.create_uid || '',
...(typeof row.default_install === 'boolean' ? { default_install: row.default_install } : {}),
...(_installStatus(row) ? { status: _installStatus(row) } : {}),
+ min_app_version: row.min_app_version || '',
};
}
@@ -979,6 +1034,7 @@ function _installMetaFromSkillRow(row: SkillInstall): Partial<InstallMeta> {
create_uid: row.create_uid || '',
...(typeof row.default_install === 'boolean' ? { default_install: row.default_install } : {}),
...(_installStatus(row) ? { status: _installStatus(row) } : {}),
+ min_app_version: row.min_app_version || '',
};
}
@@ -994,9 +1050,10 @@ function _readInstallMeta(dir: string): InstallMeta | null {
const f = path.join(dir, '_install.json');
if (!fs.existsSync(f)) return null;
try {
- const j = JSON.parse(fs.readFileSync(f, 'utf8')) as Partial<InstallMeta>;
- if (typeof j.version !== 'string' || typeof j.published_at !== 'number') return null;
- return {
+ const j = JSON.parse(fs.readFileSync(f, 'utf8')) as Partial<InstallMeta> & MinAppVersionSource;
+ if (typeof j.version !== 'string' || typeof j.published_at !== 'number') return null;
+ const minAppVersion = minAppVersionFrom(j);
+ return {
version: j.version,
published_at: j.published_at,
...(typeof j.updated_at === 'number' ? { updated_at: j.updated_at } : {}),
@@ -1011,6 +1068,7 @@ function _readInstallMeta(dir: string): InstallMeta | null {
...(typeof j.status === 'string' ? { status: j.status } : (
typeof j.state === 'string' ? { status: j.state } : {}
)),
+ ...(minAppVersion ? { min_app_version: minAppVersion } : {}),
...(typeof j.content_sha === 'string' ? { content_sha: j.content_sha } : {}),
...(typeof j.content_tree_hash === 'string' ? { content_tree_hash: j.content_tree_hash } : {}),
};
@@ -1024,7 +1082,11 @@ async function _writeInstallMeta(dir: string, meta: InstallMeta): Promise<void>
async function _patchInstallMeta(dir: string, patch: Partial<InstallMeta>): Promise<void> {
const meta = _readInstallMeta(dir);
if (!meta) return;
- await _writeInstallMeta(dir, { ...meta, ...patch });
+ const next = { ...meta, ...patch };
+ if (Object.prototype.hasOwnProperty.call(patch, 'min_app_version') && !patch.min_app_version) {
+ delete next.min_app_version;
+ }
+ await _writeInstallMeta(dir, next);
}
/** Fetch agent.json from the cloud URL recorded in the manifest, write to the per-machine
@@ -1053,7 +1115,10 @@ async function _pullAgentLocked(uid: string, row: AgentInstall, opts: Marketplac
default_install?: boolean;
status?: string;
state?: string;
+ min_app_version?: string;
+ minAppVersion?: string;
}>('/marketplace/agents/detail', { id: row.id });
+ const minAppVersion = _normalizeMinAppVersion(fresh, fresh.agent_json);
current = {
...row,
version: fresh.version,
@@ -1064,6 +1129,7 @@ async function _pullAgentLocked(uid: string, row: AgentInstall, opts: Marketplac
create_uid: fresh.create_uid || row.create_uid,
...(typeof fresh.default_install === 'boolean' ? { default_install: fresh.default_install } : {}),
...((fresh.status || fresh.state) ? { status: fresh.status || fresh.state } : {}),
+ min_app_version: minAppVersion || '',
};
_assertContinue(opts);
await addAgentInstall(uid, current);
@@ -1077,6 +1143,14 @@ async function _pullAgentLocked(uid: string, row: AgentInstall, opts: Marketplac
// Validate it parses — manifest-stored URLs come from COS, treat as untrusted.
const parsed = JSON.parse(text) as Record<string, unknown>;
if (typeof parsed.agent_id !== 'string') throw new Error('agent.json missing agent_id');
+ const minAppVersion = _normalizeMinAppVersion(current, parsed);
+ if (minAppVersion && current.min_app_version !== minAppVersion) {
+ current = { ...current, min_app_version: minAppVersion };
+ await addAgentInstall(uid, current);
+ }
+ if (!_isAppCompatible(minAppVersion)) {
+ throw new Error(`agent ${row.id} requires Orkas >= ${minAppVersion} (current ${_currentAppVersion() || 'unknown'})`);
+ }
await _ensureAgentSkillDependencies(uid, row.id, parsed, opts);
const privateSkillsZip = await _fetchAgentPrivateSkillsBundle(row.id, current.agent_skills_bundle_url || '', opts);
@@ -1104,6 +1178,7 @@ async function _pullAgentLocked(uid: string, row: AgentInstall, opts: Marketplac
create_uid: current.create_uid || '',
...(typeof current.default_install === 'boolean' ? { default_install: current.default_install } : {}),
...((current.status || current.state) ? { status: current.status || current.state } : {}),
+ ...(minAppVersion ? { min_app_version: minAppVersion } : {}),
...(((): { content_sha?: string } => {
const sha = sha256OfFile(agentJsonFile);
return sha ? { content_sha: sha } : {};
@@ -1139,7 +1214,10 @@ async function _pullSkillLocked(uid: string, row: SkillInstall, opts: Marketplac
default_install?: boolean;
status?: string;
state?: string;
+ min_app_version?: string;
+ minAppVersion?: string;
}>('/marketplace/skills/bundle', { id: row.id });
+ const minAppVersion = _normalizeMinAppVersion(fresh);
current = {
...row,
version: fresh.version,
@@ -1149,6 +1227,7 @@ async function _pullSkillLocked(uid: string, row: SkillInstall, opts: Marketplac
create_uid: fresh.create_uid || row.create_uid,
...(typeof fresh.default_install === 'boolean' ? { default_install: fresh.default_install } : {}),
...((fresh.status || fresh.state) ? { status: fresh.status || fresh.state } : {}),
+ min_app_version: minAppVersion || '',
};
_assertContinue(opts);
await addSkillInstall(uid, current);
@@ -1160,6 +1239,10 @@ async function _pullSkillLocked(uid: string, row: SkillInstall, opts: Marketplac
const ab = await res.arrayBuffer();
_assertContinue(opts);
const zip = new AdmZip(Buffer.from(ab));
+ const minAppVersion = _normalizeMinAppVersion(current);
+ if (!_isAppCompatible(minAppVersion)) {
+ throw new Error(`skill ${row.id} requires Orkas >= ${minAppVersion} (current ${_currentAppVersion() || 'unknown'})`);
+ }
const dir = userMarketplaceSkillDir(uid, row.id);
_assertContinue(opts);
@@ -1181,6 +1264,7 @@ async function _pullSkillLocked(uid: string, row: SkillInstall, opts: Marketplac
create_uid: current.create_uid || '',
...(typeof current.default_install === 'boolean' ? { default_install: current.default_install } : {}),
...((current.status || current.state) ? { status: current.status || current.state } : {}),
+ ...(minAppVersion ? { min_app_version: minAppVersion } : {}),
...(((): { content_sha?: string } => {
const sha = sha256OfFile(skillMdFile);
return sha ? { content_sha: sha } : {};
diff --git a/src/main/index.ts b/src/main/index.ts
index 0a16ce5f..1ed4ac40 100644
--- a/src/main/index.ts
+++ b/src/main/index.ts
@@ -150,7 +150,8 @@ import { getRendererTables } from './i18n';
import * as reflectionOrchestrator from './features/reflection-orchestrator';
import * as autoTasks from './features/auto_tasks';
import * as systemSkills from './features/system_skills';
-import * as builtinMarketplace from './features/builtin_marketplace';
+import * as builtinMarketplaceStartup from './features/builtin_marketplace_startup';
+import type { BuiltinMarketplaceSeedResult } from './features/builtin_marketplace';
import * as chatAttachments from './features/chat_attachments';
import * as chatArtifacts from './features/chat_artifacts';
import * as savedApps from './features/saved_apps';
@@ -428,6 +429,45 @@ function subscribeMarketplaceReconcileStatus(m: typeof import('./features/market
});
}
+function broadcastBuiltinMarketplaceSeedChanged(result: BuiltinMarketplaceSeedResult): void {
+ const pulledAgents = Math.max(0, Number(result.seeded_agents || 0) + Number(result.manifest_agents || 0));
+ const pulledSkills = Math.max(0, Number(result.seeded_skills || 0) + Number(result.manifest_skills || 0));
+ const pulled = pulledAgents + pulledSkills;
+ if (!pulled) return;
+ const base = {
+ phase: 'default_seed' as const,
+ total: pulled,
+ total_agents: pulledAgents,
+ total_skills: pulledSkills,
+ pulled_agents: pulledAgents,
+ pulled_skills: pulledSkills,
+ failed: [] as string[],
+ };
+ ipc.broadcastToRenderer('marketplace:reconcile-status', {
+ ...base,
+ state: 'running',
+ pulled: 0,
+ updated_at: Date.now(),
+ });
+ ipc.broadcastToRenderer('marketplace:reconcile-status', {
+ ...base,
+ state: 'done',
+ pulled,
+ updated_at: Date.now(),
+ });
+}
+
+async function seedBuiltinMarketplaceForCurrentUser(
+ reason: string,
+ shouldContinue?: () => boolean,
+): Promise<void> {
+ await builtinMarketplaceStartup.seedBuiltinMarketplaceForActiveUser({
+ reason,
+ shouldContinue,
+ onChanged: broadcastBuiltinMarketplaceSeedChanged,
+ });
+}
+
function marketplaceBootContextStillActive(uid: string): boolean {
if (!uid || users.isAnonymousLocalId(uid)) return false;
try { return users.getActiveUserId() === uid; }
@@ -505,6 +545,8 @@ async function runMarketplaceInstallReconcile(reason: string): Promise<void> {
marketplaceReconcileModule = m;
subscribeMarketplaceReconcileStatus(m);
+ await seedBuiltinMarketplaceForCurrentUser(reason, shouldContinue);
+
if (await mp.hasKnownDefaultInstallWork(uid)) {
m.setDefaultInstallSeedStatus(true);
defaultSeedStatusActive = true;
@@ -997,7 +1039,7 @@ if (!gotLock) {
reflectionOrchestrator.startReflectionLoop(users.getActiveUserId());
});
registerDeferred('system-skills:reconcile', () => systemSkills.reconcileAllForActiveUserWithRetry({ retries: 2, reason: 'startup' }));
- registerDeferred('builtin-marketplace:seed', () => builtinMarketplace.seedBuiltinMarketplaceForUser(users.getActiveUserId()));
+ registerDeferred('builtin-marketplace:seed', () => seedBuiltinMarketplaceForCurrentUser('startup'));
registerDeferred('auto-tasks:scheduler', () => autoTasks.startScheduler());
// Drive the immediate batch + schedule the deferred one.
diff --git a/src/main/ipc/index.ts b/src/main/ipc/index.ts
index f41b45b4..7daff239 100644
--- a/src/main/ipc/index.ts
+++ b/src/main/ipc/index.ts
@@ -1626,7 +1626,7 @@ const invokeHandlers: Record<string, InvokeHandler> = {
// Detail endpoints (cache-first) — used by the marketplace panel's detail view to render
// full content. Caller passes the list-row's (version, freshness timestamp) so we can short-circuit
// on a hot cache. Sweep is invoked once per openMarketplace at the entry point.
- 'marketplace.detailAgent': async ({ id, version, published_at, updated_at }) => {
+ 'marketplace.detailAgent': async ({ id, version, published_at, updated_at, min_app_version, minAppVersion, min_version, minVersion, min_pc_version, minPcVersion }) => {
if (!id || typeof id !== 'string') throw new Error('id required');
if (typeof version !== 'string' || typeof published_at !== 'number') {
throw new Error('version + published_at required');
@@ -1634,10 +1634,16 @@ const invokeHandlers: Record<string, InvokeHandler> = {
return marketplace.getAgentDetail(id, {
version, published_at,
...(typeof updated_at === 'number' ? { updated_at } : {}),
+ ...(typeof min_app_version === 'string' ? { min_app_version } : {}),
+ ...(typeof minAppVersion === 'string' ? { minAppVersion } : {}),
+ ...(typeof min_version === 'string' ? { min_version } : {}),
+ ...(typeof minVersion === 'string' ? { minVersion } : {}),
+ ...(typeof min_pc_version === 'string' ? { min_pc_version } : {}),
+ ...(typeof minPcVersion === 'string' ? { minPcVersion } : {}),
});
},
- 'marketplace.detailSkill': async ({ id, version, published_at, updated_at }) => {
+ 'marketplace.detailSkill': async ({ id, version, published_at, updated_at, min_app_version, minAppVersion, min_version, minVersion, min_pc_version, minPcVersion }) => {
if (!id || typeof id !== 'string') throw new Error('id required');
if (typeof version !== 'string' || typeof published_at !== 'number') {
throw new Error('version + published_at required');
@@ -1645,10 +1651,16 @@ const invokeHandlers: Record<string, InvokeHandler> = {
return marketplace.getSkillDetail(id, {
version, published_at,
...(typeof updated_at === 'number' ? { updated_at } : {}),
+ ...(typeof min_app_version === 'string' ? { min_app_version } : {}),
+ ...(typeof minAppVersion === 'string' ? { minAppVersion } : {}),
+ ...(typeof min_version === 'string' ? { min_version } : {}),
+ ...(typeof minVersion === 'string' ? { minVersion } : {}),
+ ...(typeof min_pc_version === 'string' ? { min_pc_version } : {}),
+ ...(typeof minPcVersion === 'string' ? { minPcVersion } : {}),
});
},
- 'marketplace.installAgent': async ({ id, name, version, published_at, updated_at, force }) => {
+ 'marketplace.installAgent': async ({ id, name, version, published_at, updated_at, min_app_version, minAppVersion, min_version, minVersion, min_pc_version, minPcVersion, force }) => {
if (!id || typeof id !== 'string') throw new Error('id required');
if (typeof version !== 'string' || typeof published_at !== 'number') {
throw new Error('version + published_at required');
@@ -1656,10 +1668,16 @@ const invokeHandlers: Record<string, InvokeHandler> = {
return marketplace.installMarketplaceAgent(id, {
version, published_at,
...(typeof updated_at === 'number' ? { updated_at } : {}),
+ ...(typeof min_app_version === 'string' ? { min_app_version } : {}),
+ ...(typeof minAppVersion === 'string' ? { minAppVersion } : {}),
+ ...(typeof min_version === 'string' ? { min_version } : {}),
+ ...(typeof minVersion === 'string' ? { minVersion } : {}),
+ ...(typeof min_pc_version === 'string' ? { min_pc_version } : {}),
+ ...(typeof minPcVersion === 'string' ? { minPcVersion } : {}),
}, { force: force === true, name: typeof name === 'string' ? name : undefined });
},
- 'marketplace.installSkill': async ({ id, name, version, published_at, updated_at, force }) => {
+ 'marketplace.installSkill': async ({ id, name, version, published_at, updated_at, min_app_version, minAppVersion, min_version, minVersion, min_pc_version, minPcVersion, force }) => {
if (!id || typeof id !== 'string') throw new Error('id required');
if (typeof version !== 'string' || typeof published_at !== 'number') {
throw new Error('version + published_at required');
@@ -1667,6 +1685,12 @@ const invokeHandlers: Record<string, InvokeHandler> = {
return marketplace.installMarketplaceSkill(id, {
version, published_at,
...(typeof updated_at === 'number' ? { updated_at } : {}),
+ ...(typeof min_app_version === 'string' ? { min_app_version } : {}),
+ ...(typeof minAppVersion === 'string' ? { minAppVersion } : {}),
+ ...(typeof min_version === 'string' ? { min_version } : {}),
+ ...(typeof minVersion === 'string' ? { minVersion } : {}),
+ ...(typeof min_pc_version === 'string' ? { min_pc_version } : {}),
+ ...(typeof minPcVersion === 'string' ? { minPcVersion } : {}),
}, { force: force === true, name: typeof name === 'string' ? name : undefined });
},
diff --git a/src/main/util/app-version-compat.ts b/src/main/util/app-version-compat.ts
new file mode 100644
index 00000000..2a2b5b66
--- /dev/null
+++ b/src/main/util/app-version-compat.ts
@@ -0,0 +1,60 @@
+export function versionTokens(value: unknown): Array<number | string> {
+ const text = typeof value === 'string' ? value.trim() : '';
+ if (!text) return [];
+ return text
+ .replace(/^v/i, '')
+ .split(/[.+_-]/)
+ .filter(Boolean)
+ .map((part) => (/^\d+$/.test(part) ? Number(part) : part.toLowerCase()));
+}
+
+export function compareVersions(a: unknown, b: unknown): number {
+ const aa = versionTokens(a);
+ const bb = versionTokens(b);
+ if (!aa.length || !bb.length) return 0;
+ const n = Math.max(aa.length, bb.length);
+ for (let i = 0; i < n; i++) {
+ const x = aa[i] ?? 0;
+ const y = bb[i] ?? 0;
+ if (x === y) continue;
+ if (typeof x === 'number' && typeof y === 'number') return x > y ? 1 : -1;
+ return String(x).localeCompare(String(y), undefined, { numeric: true, sensitivity: 'base' });
+ }
+ return 0;
+}
+
+export function normalizeMinAppVersion(value: unknown): string {
+ const text = typeof value === 'string' ? value.trim() : '';
+ return text || '';
+}
+
+export type MinAppVersionSource = {
+ min_app_version?: unknown;
+ minAppVersion?: unknown;
+ min_version?: unknown;
+ minVersion?: unknown;
+ min_pc_version?: unknown;
+ minPcVersion?: unknown;
+};
+
+export function minAppVersionFrom(...sources: Array<MinAppVersionSource | null | undefined>): string {
+ for (const source of sources) {
+ if (!source || typeof source !== 'object') continue;
+ const min = normalizeMinAppVersion(
+ source.min_app_version
+ ?? source.minAppVersion
+ ?? source.min_version
+ ?? source.minVersion
+ ?? source.min_pc_version
+ ?? source.minPcVersion,
+ );
+ if (min) return min;
+ }
+ return '';
+}
+
+export function satisfiesMinAppVersion(currentVersion: string, minAppVersion: string): boolean {
+ const min = normalizeMinAppVersion(minAppVersion);
+ if (!min) return true;
+ return compareVersions(currentVersion, min) >= 0;
+}
diff --git a/src/renderer/modules/marketplace.js b/src/renderer/modules/marketplace.js
index 9619f523..c1d5f8ae 100644
--- a/src/renderer/modules/marketplace.js
+++ b/src/renderer/modules/marketplace.js
@@ -177,8 +177,21 @@ function _mpNormalizeInstallMeta(row) {
const updated = row?.updated_at ?? row?.marketplace_updated_at;
if (typeof published === 'number') meta.published_at = published;
if (typeof updated === 'number') meta.updated_at = updated;
+ const minAppVersion = _mpMinAppVersion(row);
+ if (minAppVersion) meta.min_app_version = minAppVersion;
return meta;
}
+
+function _mpMinAppVersion(row) {
+ const value = row?.min_app_version
+ || row?.minAppVersion
+ || row?.min_version
+ || row?.minVersion
+ || row?.min_pc_version
+ || row?.minPcVersion
+ || '';
+ return typeof value === 'string' ? value.trim() : '';
+}
function _mpInstallMetaRows(kind) {
const ids = kind === 'agent' ? _mpState.installedAgentIds : _mpState.installedSkillIds;
const map = kind === 'agent' ? _mpState.installedAgentMeta : _mpState.installedSkillMeta;
@@ -1373,6 +1386,7 @@ async function _mpOpenDetail(kind, item, opts = {}) {
const detail = await window.orkas.invoke('marketplace.detailAgent', {
id: item.id, version: item.version,
published_at: item.published_at, updated_at: item.updated_at,
+ min_app_version: _mpMinAppVersion(item),
});
if (!detail || detail.ok === false) throw _mpErrorFromResponse(detail, 'detail failed');
_mpState.detailAgentJson = detail.agent_json;
@@ -1381,6 +1395,7 @@ async function _mpOpenDetail(kind, item, opts = {}) {
const detail = await window.orkas.invoke('marketplace.detailSkill', {
id: item.id, version: item.version,
published_at: item.published_at, updated_at: item.updated_at,
+ min_app_version: _mpMinAppVersion(item),
});
if (!detail || detail.ok === false) throw _mpErrorFromResponse(detail, 'detail failed');
const files = await window.orkas.invoke('marketplace.cacheSkillFiles', { id: item.id });
@@ -1819,6 +1834,7 @@ async function _mpInstall(kind, id, itemOverride = null) {
id, name: item.name || '',
version: item.version,
published_at: item.published_at, updated_at: item.updated_at,
+ min_app_version: _mpMinAppVersion(item),
...(force ? { force: true } : {}),
});
if (!r || r.ok === false) throw _mpInstallErrorFromResponse(r);
@@ -1922,6 +1938,7 @@ function _mpMarkInstalled(kind, item) {
version: item.version,
published_at: item.published_at,
updated_at: item.updated_at,
+ min_app_version: _mpMinAppVersion(item),
}));
}
}
diff --git a/test/main/features/builtin_marketplace_startup.test.ts b/test/main/features/builtin_marketplace_startup.test.ts
new file mode 100644
index 00000000..103a0fd1
--- /dev/null
+++ b/test/main/features/builtin_marketplace_startup.test.ts
@@ -0,0 +1,76 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+
+const postJsonMock = vi.hoisted(() => vi.fn());
+
+vi.mock('../../../src/main/features/marketplace', () => ({
+ postJson: postJsonMock,
+}));
+
+let tmpDir: string;
+let prevWs: string | undefined;
+let prevBuiltin: string | undefined;
+
+const TEST_AGENT_ID = '222222222222';
+
+beforeEach(() => {
+ tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'orkas-builtin-marketplace-startup-'));
+ prevWs = process.env.ORKAS_WORKSPACE_ROOT;
+ prevBuiltin = process.env.ORKAS_BUILTIN_ROOT;
+ process.env.ORKAS_WORKSPACE_ROOT = tmpDir;
+ process.env.ORKAS_BUILTIN_ROOT = path.join(tmpDir, 'builtin');
+ postJsonMock.mockReset();
+ vi.resetModules();
+});
+
+afterEach(() => {
+ if (prevWs === undefined) delete process.env.ORKAS_WORKSPACE_ROOT;
+ else process.env.ORKAS_WORKSPACE_ROOT = prevWs;
+ if (prevBuiltin === undefined) delete process.env.ORKAS_BUILTIN_ROOT;
+ else process.env.ORKAS_BUILTIN_ROOT = prevBuiltin;
+ fs.rmSync(tmpDir, { recursive: true, force: true });
+ vi.resetModules();
+});
+
+function writeBuiltinAgent(id: string, agentJson: Record<string, unknown>): void {
+ const root = path.join(tmpDir, 'builtin', 'marketplace', 'agents', id);
+ fs.mkdirSync(root, { recursive: true });
+ fs.writeFileSync(path.join(root, 'agent.json'), JSON.stringify({ agent_id: id, ...agentJson }, null, 2), 'utf8');
+}
+
+describe('builtin marketplace startup seed', () => {
+ it('runs for the active local user without requiring account verification', async () => {
+ writeBuiltinAgent(TEST_AGENT_ID, {
+ version: '1.0.0',
+ updated_at: '2026-07-08T00:00:00.000Z',
+ name: 'VideoStudio',
+ description: 'Creates videos',
+ category: 'creation',
+ });
+
+ const users = await import('../../../src/main/features/users');
+ const paths = await import('../../../src/main/paths');
+ const startup = await import('../../../src/main/features/builtin_marketplace_startup');
+ users.activateUser('u1');
+
+ const changed: unknown[] = [];
+ await expect(startup.seedBuiltinMarketplaceForActiveUser({
+ reason: 'test',
+ onChanged: (result) => changed.push(result),
+ })).resolves.toMatchObject({
+ seeded_agents: 1,
+ manifest_agents: 1,
+ });
+
+ expect(fs.existsSync(path.join(paths.userMarketplaceAgentDir('u1', TEST_AGENT_ID), 'agent.json'))).toBe(true);
+ expect(changed).toHaveLength(1);
+ });
+
+ it('returns null when boot has not activated a user yet', async () => {
+ const startup = await import('../../../src/main/features/builtin_marketplace_startup');
+
+ await expect(startup.seedBuiltinMarketplaceForActiveUser({ reason: 'test' })).resolves.toBeNull();
+ });
+});
diff --git a/test/main/util/app-version-compat.test.ts b/test/main/util/app-version-compat.test.ts
new file mode 100644
index 00000000..6abe2f4a
--- /dev/null
+++ b/test/main/util/app-version-compat.test.ts
@@ -0,0 +1,26 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+ minAppVersionFrom,
+ satisfiesMinAppVersion,
+} from '../../../src/main/util/app-version-compat';
+
+describe('app version compatibility', () => {
+ it('treats missing minimum app version as unrestricted', () => {
+ expect(satisfiesMinAppVersion('1.0.0', '')).toBe(true);
+ expect(satisfiesMinAppVersion('', '')).toBe(true);
+ });
+
+ it('normalizes canonical, simple, and legacy minimum-version fields', () => {
+ expect(minAppVersionFrom({ min_app_version: ' 1.5.0 ' })).toBe('1.5.0');
+ expect(minAppVersionFrom({ min_version: '1.4.0' })).toBe('1.4.0');
+ expect(minAppVersionFrom({ min_pc_version: '1.3.0' })).toBe('1.3.0');
+ expect(minAppVersionFrom({ min_version: '1.4.0' }, { min_app_version: '1.5.0' })).toBe('1.4.0');
+ });
+
+ it('compares current app version with the required minimum', () => {
+ expect(satisfiesMinAppVersion('1.5.0', '1.5.0')).toBe(true);
+ expect(satisfiesMinAppVersion('1.5.1', '1.5.0')).toBe(true);
+ expect(satisfiesMinAppVersion('1.4.9', '1.5.0')).toBe(false);
+ });
+});