dominds 1.5.1 → 1.6.0

package/dist/apps/configuration-file.js

@@ -5,6 +5,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.APPS_CONFIGURATION_REL_PATH = exports.DEFAULT_APPS_RESOLUTION_STRATEGY = void 0;
 exports.parseResolutionStrategy = parseResolutionStrategy;
+exports.normalizeAppsResolutionStrategy = normalizeAppsResolutionStrategy;
 exports.loadAppsConfigurationFile = loadAppsConfigurationFile;
 exports.writeAppsConfigurationFile = writeAppsConfigurationFile;
 exports.writeAppsConfigurationFileIfChanged = writeAppsConfigurationFileIfChanged;
@@ -91,6 +92,26 @@ function parseResolutionStrategy(v, at) {
         },
     };
 }
+function normalizeAppsResolutionStrategy(raw) {
+    const order = raw?.order ??
+        exports.DEFAULT_APPS_RESOLUTION_STRATEGY.order ??
+        ['local'];
+    const localRoots = raw?.localRoots ??
+        exports.DEFAULT_APPS_RESOLUTION_STRATEGY.localRoots ?? ['dominds-apps'];
+    if (order.length === 0) {
+        throw new Error(`Invalid ${exports.APPS_CONFIGURATION_REL_PATH}: resolutionStrategy.order must not be empty`);
+    }
+    if (localRoots.length === 0) {
+        throw new Error(`Invalid ${exports.APPS_CONFIGURATION_REL_PATH}: resolutionStrategy.localRoots must not be empty`);
+    }
+    if (new Set(order).size !== order.length) {
+        throw new Error(`Invalid ${exports.APPS_CONFIGURATION_REL_PATH}: resolutionStrategy.order has duplicates`);
+    }
+    if (new Set(localRoots).size !== localRoots.length) {
+        throw new Error(`Invalid ${exports.APPS_CONFIGURATION_REL_PATH}: resolutionStrategy.localRoots has duplicates`);
+    }
+    return { order, localRoots };
+}
 function canonicalizeConfigurationFile(file) {
     const disabledApps = file.disabledApps
         ? [

package/dist/apps/enabled-apps.js

@@ -5,11 +5,11 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.materializeAppsResolution = materializeAppsResolution;
 exports.loadEnabledAppsSnapshot = loadEnabledAppsSnapshot;
-const promises_1 = __importDefault(require("node:fs/promises"));
 const node_path_1 = __importDefault(require("node:path"));
 const app_lock_file_1 = require("./app-lock-file");
 const assigned_port_1 = require("./assigned-port");
 const configuration_file_1 = require("./configuration-file");
+const local_package_root_1 = require("./local-package-root");
 const manifest_1 = require("./manifest");
 const package_info_1 = require("./package-info");
 const resolution_file_1 = require("./resolution-file");
@@ -20,62 +20,12 @@ function getRuntimePort(entry) {
     const defaultPort = entry.installJson.frontend?.defaultPort;
     return typeof defaultPort === 'number' && defaultPort > 0 ? defaultPort : null;
 }
-async function dirExists(dirPathAbs) {
-    try {
-        const stat = await promises_1.default.stat(dirPathAbs);
-        return stat.isDirectory();
-    }
-    catch (err) {
-        const isEnoent = typeof err === 'object' &&
-            err !== null &&
-            'code' in err &&
-            err.code === 'ENOENT';
-        if (isEnoent)
-            return false;
-        throw err;
-    }
-}
-function normalizeStrategy(raw) {
-    const order = raw?.order ??
-        configuration_file_1.DEFAULT_APPS_RESOLUTION_STRATEGY.order ??
-        ['local'];
-    const localRoots = raw?.localRoots ??
-        configuration_file_1.DEFAULT_APPS_RESOLUTION_STRATEGY.localRoots ?? ['dominds-apps'];
-    if (order.length === 0) {
-        throw new Error(`Invalid ${configuration_file_1.APPS_CONFIGURATION_REL_PATH}: resolutionStrategy.order must not be empty`);
-    }
-    if (localRoots.length === 0) {
-        throw new Error(`Invalid ${configuration_file_1.APPS_CONFIGURATION_REL_PATH}: resolutionStrategy.localRoots must not be empty`);
-    }
-    if (new Set(order).size !== order.length) {
-        throw new Error(`Invalid ${configuration_file_1.APPS_CONFIGURATION_REL_PATH}: resolutionStrategy.order has duplicates`);
-    }
-    if (new Set(localRoots).size !== localRoots.length) {
-        throw new Error(`Invalid ${configuration_file_1.APPS_CONFIGURATION_REL_PATH}: resolutionStrategy.localRoots has duplicates`);
-    }
-    return { order, localRoots };
-}
 function getResolutionHint(params) {
     const filePathAbs = node_path_1.default.resolve(params.rtwsRootAbs, configuration_file_1.APPS_CONFIGURATION_REL_PATH);
     const action = params.hasConfigurationFile ? 'Edit' : 'Create';
     return (`${action} ${filePathAbs} to configure 'resolutionStrategy'. ` +
         `Default local root is 'dominds-apps' (rtws-relative) and expects local apps at '<root>/<appId>/'.`);
 }
-async function resolveLocalAppPackageRootAbs(params) {
-    const candidates = new Set();
-    if (params.previousResolutionEntry?.source.kind === 'local') {
-        candidates.add(params.previousResolutionEntry.source.pathAbs);
-    }
-    for (const root of params.localRoots) {
-        const rootAbs = node_path_1.default.isAbsolute(root) ? root : node_path_1.default.resolve(params.rtwsRootAbs, root);
-        candidates.add(node_path_1.default.resolve(rootAbs, params.appId));
-    }
-    for (const candidateAbs of candidates) {
-        if (await dirExists(candidateAbs))
-            return candidateAbs;
-    }
-    return null;
-}
 async function loadManifestDepsFromResolvedApp(params) {
     const pkgInfo = await (0, package_info_1.readPackageInfo)({ packageRootAbs: params.packageRootAbs });
     const loaded = await (0, manifest_1.loadDomindsAppManifest)({
@@ -103,7 +53,7 @@ function buildNpxSpec(params) {
 async function probeAppByStrategy(params) {
     for (const item of params.strategy.order) {
         if (item === 'local') {
-            const packageRootAbs = await resolveLocalAppPackageRootAbs({
+            const packageRootAbs = await (0, local_package_root_1.resolveLocalAppPackageRootAbs)({
                 rtwsRootAbs: params.rtwsRootAbs,
                 appId: params.appId,
                 localRoots: params.strategy.localRoots,
@@ -426,7 +376,7 @@ async function materializeAppsResolution(params) {
     }
     const resolved = await resolveGraph({
         rtwsRootAbs: params.rtwsRootAbs,
-        strategy: normalizeStrategy(loadedConfig.file.resolutionStrategy),
+        strategy: (0, configuration_file_1.normalizeAppsResolutionStrategy)(loadedConfig.file.resolutionStrategy),
         configurationDisabledApps: new Set(loadedConfig.file.disabledApps ?? []),
         previousResolutionById,
         lockedHintsById,

package/dist/apps/local-package-root.js

@@ -0,0 +1,41 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveLocalAppPackageRootAbs = resolveLocalAppPackageRootAbs;
+const promises_1 = __importDefault(require("node:fs/promises"));
+const node_path_1 = __importDefault(require("node:path"));
+async function dirExists(dirPathAbs) {
+    try {
+        const stat = await promises_1.default.stat(dirPathAbs);
+        return stat.isDirectory();
+    }
+    catch (err) {
+        const isEnoent = typeof err === 'object' &&
+            err !== null &&
+            'code' in err &&
+            err.code === 'ENOENT';
+        if (isEnoent)
+            return false;
+        throw err;
+    }
+}
+async function resolveLocalAppPackageRootAbs(params) {
+    const candidates = new Set();
+    const trimmedAppId = params.appId.trim();
+    if (trimmedAppId === '')
+        return null;
+    if (params.previousResolutionEntry?.source.kind === 'local') {
+        candidates.add(params.previousResolutionEntry.source.pathAbs);
+    }
+    for (const root of params.localRoots) {
+        const rootAbs = node_path_1.default.isAbsolute(root) ? root : node_path_1.default.resolve(params.rtwsRootAbs, root);
+        candidates.add(node_path_1.default.resolve(rootAbs, trimmedAppId));
+    }
+    for (const candidateAbs of candidates) {
+        if (await dirExists(candidateAbs))
+            return candidateAbs;
+    }
+    return null;
+}

package/dist/apps/runtime.js

@@ -6,6 +6,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.getAppsHostClient = getAppsHostClient;
 exports.shutdownAppsRuntime = shutdownAppsRuntime;
 exports.registerEnabledAppsToolProxies = registerEnabledAppsToolProxies;
+exports.listDynamicAppToolsetsForMember = listDynamicAppToolsetsForMember;
 exports.initAppsRuntime = initAppsRuntime;
 const crypto_1 = require("crypto");
 const promises_1 = __importDefault(require("fs/promises"));
@@ -251,6 +252,7 @@ function registerAppArtifacts(app) {
                     dialogId: dlg.id.selfId,
                     rootDialogId: dlg.id.rootId,
                     agentId: dlg.agentId,
+                    taskDocPath: dlg.taskDocPath,
                     sessionSlug: dlg instanceof dialog_1.SubDialog ? dlg.sessionSlug : undefined,
                     callerId: caller.id,
                 });
@@ -364,6 +366,14 @@ async function registerEnabledAppsToolProxies(params) {
     refreshQueue = run.catch(() => undefined);
     await run;
 }
+async function listDynamicAppToolsetsForMember(_params) {
+    await registerEnabledAppsToolProxies({ rtwsRootAbs: _params.rtwsRootAbs });
+    const host = await ensureAppsHostReadyForToolCalls();
+    return await host.listDynamicToolsets({
+        memberId: _params.memberId,
+        taskDocPath: _params.taskDocPath,
+    });
+}
 async function initAppsRuntime(params) {
     appsRuntimeConfig = {
         rtwsRootAbs: params.rtwsRootAbs,

package/dist/apps-host/client.js

@@ -18,6 +18,17 @@ function isRecord(v) {
 function asString(v) {
     return typeof v === 'string' ? v : null;
 }
+function asStringArray(v) {
+    if (!Array.isArray(v))
+        return null;
+    const out = [];
+    for (const item of v) {
+        if (typeof item !== 'string')
+            return null;
+        out.push(item);
+    }
+    return out;
+}
 function parseMessageToKernel(v) {
     if (!isRecord(v))
         throw new Error('Invalid IPC message from apps-host: expected object');
@@ -46,6 +57,27 @@ function parseMessageToKernel(v) {
             throw new Error('Invalid tool_result message: callId required');
         return v;
     }
+    if (type === 'dynamic_toolsets_result') {
+        const callId = asString(v['callId']);
+        if (!callId)
+            throw new Error('Invalid dynamic_toolsets_result message: callId required');
+        const ok = v['ok'];
+        if (ok === true) {
+            const toolsetIds = asStringArray(v['toolsetIds']);
+            if (toolsetIds === null) {
+                throw new Error('Invalid dynamic_toolsets_result message: toolsetIds must be string[]');
+            }
+            return { type, callId, ok: true, toolsetIds };
+        }
+        if (ok === false) {
+            const errorText = asString(v['errorText']);
+            if (!errorText) {
+                throw new Error('Invalid dynamic_toolsets_result message: errorText required when ok=false');
+            }
+            return { type, callId, ok: false, errorText };
+        }
+        return v;
+    }
     if (type === 'reminder_apply_result') {
         const callId = asString(v['callId']);
         if (!callId)
@@ -101,6 +133,7 @@ async function startAppsHost(params) {
         throw new Error('Failed to start apps-host: child process has no IPC channel');
     }
     const pendingTools = new Map();
+    const pendingDynamicToolsets = new Map();
     const pendingRunControls = new Map();
     const pendingReminderApplies = new Map();
     const pendingReminderUpdates = new Map();
@@ -122,6 +155,11 @@ async function startAppsHost(params) {
             p.reject(err);
         }
         pendingTools.clear();
+        for (const p of pendingDynamicToolsets.values()) {
+            clearTimeout(p.timeout);
+            p.reject(err);
+        }
+        pendingDynamicToolsets.clear();
         for (const p of pendingRunControls.values()) {
             clearTimeout(p.timeout);
             p.reject(err);
@@ -187,6 +225,20 @@ async function startAppsHost(params) {
                     p.reject(new Error(msg.errorText));
                 return;
             }
+            if (msg.type === 'dynamic_toolsets_result') {
+                const p = pendingDynamicToolsets.get(msg.callId);
+                if (!p) {
+                    throw new Error(`Unexpected dynamic_toolsets_result for unknown callId: ${msg.callId}`);
+                }
+                pendingDynamicToolsets.delete(msg.callId);
+                clearTimeout(p.timeout);
+                if (!msg.ok) {
+                    p.reject(new Error(msg.errorText));
+                    return;
+                }
+                p.resolve(msg.toolsetIds);
+                return;
+            }
             if (msg.type === 'run_control_result') {
                 const p = pendingRunControls.get(msg.callId);
                 if (!p) {
@@ -273,6 +325,25 @@ async function startAppsHost(params) {
             child.send(msg);
         });
     };
+    const listDynamicToolsets = async (ctx) => {
+        if (!ready) {
+            throw new Error('apps-host is not ready yet (dynamicToolsets)');
+        }
+        const callId = (0, crypto_1.randomUUID)();
+        const msg = {
+            type: 'dynamic_toolsets',
+            callId,
+            ctx,
+        };
+        return await new Promise((resolve, reject) => {
+            const timeout = setTimeout(() => {
+                pendingDynamicToolsets.delete(callId);
+                reject(new Error(`apps-host dynamic toolsets call timed out: callId=${callId}`));
+            }, 60000);
+            pendingDynamicToolsets.set(callId, { resolve, reject, timeout });
+            child.send(msg);
+        });
+    };
     const applyRunControl = async (controlId, payload) => {
         if (!ready) {
             throw new Error(`apps-host is not ready yet (runControl=${controlId})`);
@@ -358,19 +429,71 @@ async function startAppsHost(params) {
         });
     };
     const shutdown = async () => {
+        const awaitChildExit = () => {
+            if (child.exitCode !== null || child.signalCode !== null) {
+                return Promise.resolve();
+            }
+            return new Promise((resolve) => {
+                let settled = false;
+                const cleanup = () => {
+                    child.off('exit', onExit);
+                    child.off('error', onError);
+                    clearTimeout(timeout);
+                };
+                const finish = () => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    cleanup();
+                    resolve();
+                };
+                const onExit = () => {
+                    finish();
+                };
+                const onError = () => {
+                    finish();
+                };
+                const timeout = setTimeout(() => {
+                    try {
+                        child.kill('SIGTERM');
+                    }
+                    catch (err) {
+                        log.warn('Failed to SIGTERM timed-out apps-host during shutdown', err instanceof Error ? err : new Error(String(err)));
+                    }
+                    finish();
+                }, 5000);
+                child.once('exit', onExit);
+                child.once('error', onError);
+            });
+        };
         try {
             child.send({ type: 'shutdown' });
         }
         catch (err) {
             log.warn('Failed to send shutdown to apps-host', err instanceof Error ? err : new Error(String(err)));
+            try {
+                child.kill('SIGTERM');
+            }
+            catch (killErr) {
+                log.warn('Failed to SIGTERM apps-host after shutdown send failure', killErr instanceof Error ? killErr : new Error(String(killErr)));
+            }
         }
         failAllPending(new Error('apps-host shutdown'));
+        await awaitChildExit();
     };
     if (!readyMsg) {
         throw new Error('apps-host: internal error (readyMsg missing after readyPromise resolved)');
     }
     return {
-        client: { callTool, applyRunControl, applyReminder, updateReminder, renderReminder, shutdown },
+        client: {
+            callTool,
+            listDynamicToolsets,
+            applyRunControl,
+            applyReminder,
+            updateReminder,
+            renderReminder,
+            shutdown,
+        },
         ready: readyResult,
     };
 }

package/dist/apps-host/host.js

@@ -28,6 +28,9 @@ function isJsonValue(value) {
         return false;
     return Object.values(value).every((item) => isJsonValue(item));
 }
+function isStringArray(value) {
+    return Array.isArray(value) && value.every((item) => typeof item === 'string');
+}
 function isToolCallOutput(value) {
     if (typeof value === 'string')
         return true;
@@ -217,6 +220,7 @@ const runningApps = new Map();
 const toolHandlers = new Map();
 const runControlHandlers = new Map();
 const reminderOwnerHandlers = new Map();
+const dynamicToolsetHandlers = new Map();
 function buildReminderOwnerHandlerKey(appId, ownerRef) {
     return `${appId}::${ownerRef}`;
 }
@@ -253,6 +257,10 @@ function validateHostInstance(host, appId) {
     if (reminderOwners !== undefined && !isRecord(reminderOwners)) {
         throw new Error(`Invalid app host instance for '${appId}': reminderOwners must be an object`);
     }
+    const dynamicToolsets = host['dynamicToolsets'];
+    if (dynamicToolsets !== undefined && typeof dynamicToolsets !== 'function') {
+        throw new Error(`Invalid app host instance for '${appId}': dynamicToolsets must be a function`);
+    }
     const toolFns = tools;
     for (const [name, fn] of Object.entries(toolFns)) {
         if (typeof fn !== 'function') {
@@ -341,6 +349,9 @@ async function initOnce(msg) {
                 reminderOwnerHandlers.set(handlerKey, { appId, ownerRef, fn });
             }
         }
+        if (host.dynamicToolsets) {
+            dynamicToolsetHandlers.set(appId, host.dynamicToolsets);
+        }
         let frontend = null;
         if (app.installJson.frontend) {
             if (!host.start) {
@@ -430,6 +441,48 @@ process.on('message', (raw) => {
                 }
                 return;
             }
+            case 'dynamic_toolsets': {
+                try {
+                    const collected = new Set();
+                    for (const [appId, handler] of dynamicToolsetHandlers.entries()) {
+                        try {
+                            const toolsetIds = await handler(msg.ctx);
+                            if (!isStringArray(toolsetIds)) {
+                                throw new Error('dynamicToolsets() must return string[]');
+                            }
+                            for (const toolsetId of toolsetIds) {
+                                if (toolsetId.trim() !== '') {
+                                    collected.add(toolsetId);
+                                }
+                            }
+                        }
+                        catch (err) {
+                            send({
+                                type: 'log',
+                                level: 'error',
+                                msg: `dynamic_toolsets failed: ${err instanceof Error ? err.message : String(err)}`,
+                                appId,
+                            });
+                            throw err;
+                        }
+                    }
+                    send({
+                        type: 'dynamic_toolsets_result',
+                        callId: msg.callId,
+                        ok: true,
+                        toolsetIds: [...collected],
+                    });
+                }
+                catch (err) {
+                    send({
+                        type: 'dynamic_toolsets_result',
+                        callId: msg.callId,
+                        ok: false,
+                        errorText: err instanceof Error ? err.message : String(err),
+                    });
+                }
+                return;
+            }
             case 'run_control_apply': {
                 const found = runControlHandlers.get(msg.controlId);
                 if (!found) {

package/dist/apps-host/ipc-types.js

@@ -158,6 +158,7 @@ function parseAppsHostMessageFromKernel(v) {
         const dialogId = asString(ctx['dialogId']);
         const rootDialogId = asString(ctx['rootDialogId']);
         const agentId = asString(ctx['agentId']);
+        const taskDocPath = asString(ctx['taskDocPath']);
         const sessionSlugRaw = ctx['sessionSlug'];
         const sessionSlug = sessionSlugRaw === undefined
             ? undefined
@@ -171,6 +172,8 @@ function parseAppsHostMessageFromKernel(v) {
             throw new Error('Invalid tool_call message: ctx.rootDialogId required');
         if (!agentId)
             throw new Error('Invalid tool_call message: ctx.agentId required');
+        if (!taskDocPath)
+            throw new Error('Invalid tool_call message: ctx.taskDocPath required');
         if (sessionSlugRaw !== undefined && !sessionSlug) {
             throw new Error('Invalid tool_call message: ctx.sessionSlug must be string when present');
         }
@@ -182,7 +185,64 @@ function parseAppsHostMessageFromKernel(v) {
             callId,
             toolName,
             args: args,
-            ctx: { dialogId, rootDialogId, agentId, sessionSlug: normalizedSessionSlug, callerId },
+            ctx: {
+                dialogId,
+                rootDialogId,
+                agentId,
+                taskDocPath,
+                sessionSlug: normalizedSessionSlug,
+                callerId,
+            },
+        };
+    }
+    if (type === 'dynamic_toolsets') {
+        const callId = asString(v['callId']);
+        const ctx = v['ctx'];
+        if (!callId)
+            throw new Error('Invalid dynamic_toolsets message: callId required');
+        if (!isRecord(ctx))
+            throw new Error('Invalid dynamic_toolsets message: ctx must be object');
+        const memberId = asString(ctx['memberId']);
+        const taskDocPath = asString(ctx['taskDocPath']);
+        const dialogIdRaw = ctx['dialogId'];
+        const dialogId = dialogIdRaw === undefined ? undefined : asString(dialogIdRaw);
+        const rootDialogIdRaw = ctx['rootDialogId'];
+        const rootDialogId = rootDialogIdRaw === undefined ? undefined : asString(rootDialogIdRaw);
+        const agentIdRaw = ctx['agentId'];
+        const agentId = agentIdRaw === undefined ? undefined : asString(agentIdRaw);
+        const sessionSlugRaw = ctx['sessionSlug'];
+        const sessionSlug = sessionSlugRaw === undefined ? undefined : asString(sessionSlugRaw);
+        if (!memberId)
+            throw new Error('Invalid dynamic_toolsets message: ctx.memberId required');
+        if (!taskDocPath)
+            throw new Error('Invalid dynamic_toolsets message: ctx.taskDocPath required');
+        if (dialogIdRaw !== undefined && dialogId === null) {
+            throw new Error('Invalid dynamic_toolsets message: ctx.dialogId must be string when present');
+        }
+        if (rootDialogIdRaw !== undefined && rootDialogId === null) {
+            throw new Error('Invalid dynamic_toolsets message: ctx.rootDialogId must be string when present');
+        }
+        if (agentIdRaw !== undefined && agentId === null) {
+            throw new Error('Invalid dynamic_toolsets message: ctx.agentId must be string when present');
+        }
+        if (sessionSlugRaw !== undefined && sessionSlug === null) {
+            throw new Error('Invalid dynamic_toolsets message: ctx.sessionSlug must be string when present');
+        }
+        const normalizedDialogId = dialogId ?? undefined;
+        const normalizedRootDialogId = rootDialogId ?? undefined;
+        const normalizedAgentId = agentId ?? undefined;
+        const normalizedSessionSlug = sessionSlug ?? undefined;
+        return {
+            type: 'dynamic_toolsets',
+            callId,
+            ctx: {
+                memberId,
+                taskDocPath,
+                dialogId: normalizedDialogId,
+                rootDialogId: normalizedRootDialogId,
+                agentId: normalizedAgentId,
+                sessionSlug: normalizedSessionSlug,
+            },
         };
     }
     if (type === 'reminder_apply') {

package/dist/cli/install.js

@@ -15,6 +15,7 @@ const promises_1 = __importDefault(require("node:fs/promises"));
 const node_path_1 = __importDefault(require("node:path"));
 const app_lock_file_1 = require("../apps/app-lock-file");
 const configuration_file_1 = require("../apps/configuration-file");
+const local_package_root_1 = require("../apps/local-package-root");
 const manifest_1 = require("../apps/manifest");
 const resolution_file_1 = require("../apps/resolution-file");
 const run_app_json_1 = require("../apps/run-app-json");
@@ -83,6 +84,34 @@ async function pathIsDirectory(pathAbs) {
         return false;
     }
 }
+async function resolveInstallSource(params) {
+    if (params.treatAsExplicitLocalPath) {
+        return { kind: 'local', packageRootAbs: node_path_1.default.resolve(params.rtwsRootAbs, params.specOrPath) };
+    }
+    const loadedConfig = await (0, configuration_file_1.loadAppsConfigurationFile)({ rtwsRootAbs: params.rtwsRootAbs });
+    if (loadedConfig.kind === 'error') {
+        throw new Error(`failed to read .apps/configuration.yaml: ${loadedConfig.errorText}`);
+    }
+    const strategy = (0, configuration_file_1.normalizeAppsResolutionStrategy)(loadedConfig.file.resolutionStrategy);
+    for (const item of strategy.order) {
+        if (item === 'local') {
+            const packageRootAbs = await (0, local_package_root_1.resolveLocalAppPackageRootAbs)({
+                rtwsRootAbs: params.rtwsRootAbs,
+                appId: params.specOrPath,
+                localRoots: strategy.localRoots,
+                previousResolutionEntry: null,
+            });
+            if (packageRootAbs !== null)
+                return { kind: 'local', packageRootAbs };
+            continue;
+        }
+        if (item === 'npx')
+            return { kind: 'npx', spec: params.specOrPath };
+        const exhaustive = item;
+        throw new Error(`Unreachable install resolution strategy item: ${String(exhaustive)}`);
+    }
+    return { kind: 'npx', spec: params.specOrPath };
+}
 async function main() {
     const rtwsRootAbs = process.cwd();
     let args;
@@ -102,10 +131,14 @@ async function main() {
         return;
     }
     const localAbs = node_path_1.default.resolve(rtwsRootAbs, specOrPath);
-    const shouldUseLocal = args.local || (await pathIsDirectory(localAbs));
-    const installJson = shouldUseLocal
-        ? await (0, run_app_json_1.runDomindsAppJsonViaLocalPackage)({ packageRootAbs: localAbs })
-        : await (0, run_app_json_1.runDomindsAppJsonViaNpx)({ spec: specOrPath, cwdAbs: rtwsRootAbs });
+    const installSource = await resolveInstallSource({
+        rtwsRootAbs,
+        specOrPath,
+        treatAsExplicitLocalPath: args.local || (await pathIsDirectory(localAbs)),
+    });
+    const installJson = installSource.kind === 'local'
+        ? await (0, run_app_json_1.runDomindsAppJsonViaLocalPackage)({ packageRootAbs: installSource.packageRootAbs })
+        : await (0, run_app_json_1.runDomindsAppJsonViaNpx)({ spec: installSource.spec, cwdAbs: rtwsRootAbs });
     if (args.idOverride && args.idOverride !== installJson.appId) {
         console.error(`Error: --id '${args.idOverride}' does not match appId '${installJson.appId}'`);
         process.exit(1);
@@ -156,7 +189,7 @@ async function main() {
         },
     });
     await (0, app_lock_file_1.writeAppLockFileIfChanged)({ rtwsRootAbs, file: nextLock });
-    if (shouldUseLocal) {
+    if (installSource.kind === 'local') {
         const loadedResolution = await (0, resolution_file_1.loadAppsResolutionFile)({ rtwsRootAbs });
         if (loadedResolution.kind === 'error') {
             console.error(`Error: failed to read .apps/resolution.yaml: ${loadedResolution.errorText}`);
@@ -168,7 +201,7 @@ async function main() {
             next: {
                 id: installJson.appId,
                 enabled: true,
-                source: { kind: 'local', pathAbs: localAbs },
+                source: { kind: 'local', pathAbs: installSource.packageRootAbs },
                 assignedPort: null,
                 installJson,
             },
@@ -177,8 +210,8 @@ async function main() {
     }
     await (0, workspace_app_state_1.refreshAppsDerivedState)({ rtwsRootAbs });
     void args.force;
-    console.log(shouldUseLocal
-        ? `Installed app '${installJson.appId}' from local package: ${localAbs}`
+    console.log(installSource.kind === 'local'
+        ? `Installed app '${installJson.appId}' from local package: ${installSource.packageRootAbs}`
         : `Installed app '${installJson.appId}' via resolver strategy seed: ${specOrPath}`);
     if (args.enable) {
         console.log(`Enabled app '${installJson.appId}'`);