jishushell 0.5.22 → 0.6.18

package/dist/cli/app.js

@@ -1,10 +1,11 @@
 import { existsSync, readFileSync } from "fs";
 import { basename, extname } from "path";
-import { stringify } from "yaml";
 import { parseFlag } from "./helpers.js";
 import { loadManagedListEntries, printManagedList } from "./managed-list.js";
-import { ensureNomadToken, execInInstance, getInstanceLogs, getInstanceStatus, readInstanceMeta, restartNomadJobInstance, startNomadJobInstance, stopNomadJobInstance, } from "../services/nomad-manager.js";
-import { getTask, subscribeTask } from "../services/task-registry.js";
+import { ensureNomadToken, execInInstance, getInstanceLogs, getInstanceStatus, readInstanceMeta, submitIntegrationRuntimeJob, stopIntegrationRuntimeJob, } from "../services/runtime/drivers/nomad.js";
+import { markRuntimeRepairRestartApplied } from "../services/repair/runtime-repair.js";
+import { getTask, subscribeTask } from "../services/tasks/registry.js";
+import { resolveRuntimeCapabilityPort } from "../services/app-common/service.js";
 // ── ANSI colour helpers ───────────────────────────────────────────────────
 const isTTY = process.stdout.isTTY ?? false;
 const c = {
@@ -73,17 +74,67 @@ async function runManagedAppTask(starter, successMessage) {
     if (!started.ok) {
         log(c.red(`  ✗  ${started.error || "Task failed"}`));
         process.exitCode = 1;
-        return;
+        return false;
     }
     if (started.taskId) {
         const result = await waitForLocalTask(started.taskId);
         if (result.status === "error") {
             log(c.red(`  ✗  ${result.message || "Task failed"}`));
             process.exitCode = 1;
-            return;
+            return false;
         }
     }
     log(c.green(`  ✓  ${successMessage}`));
+    return true;
+}
+const LEGACY_RAW_RUNTIME_RESTART_SETTLE_MS = 2_000;
+function logLegacyRawRuntimeWarning(instanceId) {
+    log(c.yellow(`  !  No Core instance record found for "${instanceId}"; using legacy raw runtime operation. `
+        + "Run repair/migration before normal lifecycle operations."));
+}
+async function runLegacyRawRuntimeStart(instanceId) {
+    // Legacy/repair boundary only. Managed instances must go through lifecycle-service.
+    logLegacyRawRuntimeWarning(instanceId);
+    const result = await submitIntegrationRuntimeJob(instanceId);
+    if (result.ok) {
+        markRuntimeRepairRestartApplied(instanceId);
+        log(c.green(`  ✓  Started: ${readInstanceMeta(instanceId)?.name || instanceId}`));
+        return;
+    }
+    log(c.red(`  ✗  ${result.error || "Start failed"}`));
+    process.exitCode = 1;
+}
+async function runLegacyRawRuntimeStop(instanceId, purge) {
+    // Legacy/repair boundary only. Managed instances must go through lifecycle-service.
+    logLegacyRawRuntimeWarning(instanceId);
+    const result = await stopIntegrationRuntimeJob(instanceId, purge);
+    if (result.ok) {
+        log(c.green(`  ✓  Stopped: ${readInstanceMeta(instanceId)?.name || instanceId}${purge ? " (purged)" : ""}`));
+        return;
+    }
+    log(c.red(`  ✗  ${result.error || "Stop failed"}`));
+    process.exitCode = 1;
+}
+async function runLegacyRawRuntimeRestart(instanceId) {
+    // Legacy/repair boundary only. Managed instances must go through lifecycle-service.
+    logLegacyRawRuntimeWarning(instanceId);
+    const stopResult = await stopIntegrationRuntimeJob(instanceId);
+    if (!stopResult.ok && !stopResult.error?.includes("not running") && !stopResult.error?.includes("not found")) {
+        log(c.red(`  ✗  ${stopResult.error || "Restart failed"}`));
+        process.exitCode = 1;
+        return;
+    }
+    // Legacy raw runtime restart may need a short gap between stop/start until
+    // the repair path is retired behind canonical lifecycle state.
+    await new Promise((resolve) => setTimeout(resolve, LEGACY_RAW_RUNTIME_RESTART_SETTLE_MS));
+    const result = await submitIntegrationRuntimeJob(instanceId);
+    if (result.ok) {
+        markRuntimeRepairRestartApplied(instanceId);
+        log(c.green(`  ✓  Restarted: ${readInstanceMeta(instanceId)?.name || instanceId}`));
+        return;
+    }
+    log(c.red(`  ✗  ${result.error || "Restart failed"}`));
+    process.exitCode = 1;
 }
 function readPassword(prompt) {
     return new Promise((resolve, reject) => {
@@ -193,12 +244,63 @@ async function runManagedUninstallTask(starter, successMessage, sudoState) {
         return;
     }
 }
-function rewriteInstalledAppYaml(yamlText, sourceId, targetId) {
-    const homeDir = process.env.HOME ?? "";
-    return yamlText
-        .split(`~/.jishushell/apps/${sourceId}`).join(`~/.jishushell/apps/${targetId}`)
-        .split(`$HOME/.jishushell/apps/${sourceId}`).join(`$HOME/.jishushell/apps/${targetId}`)
-        .split(`${homeDir}/.jishushell/apps/${sourceId}`).join(`${homeDir}/.jishushell/apps/${targetId}`);
+function readFlagValue(args, index, flag) {
+    const inlinePrefix = `${flag}=`;
+    const current = args[index];
+    if (current.startsWith(inlinePrefix)) {
+        const value = current.slice(inlinePrefix.length);
+        if (!value)
+            throw new Error(`Missing value for ${flag}`);
+        return { value, nextIndex: index };
+    }
+    const value = args[index + 1];
+    if (!value || value.startsWith("--"))
+        throw new Error(`Missing value for ${flag}`);
+    return { value, nextIndex: index + 1 };
+}
+function parseCreateArgs(args) {
+    const parsed = {};
+    const positional = [];
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (!arg.startsWith("--")) {
+            positional.push(arg);
+            continue;
+        }
+        if (arg === "--name" || arg.startsWith("--name=")) {
+            const result = readFlagValue(args, i, "--name");
+            parsed.name = result.value;
+            i = result.nextIndex;
+        }
+        else if (arg === "--description" || arg.startsWith("--description=")) {
+            const result = readFlagValue(args, i, "--description");
+            parsed.description = result.value;
+            i = result.nextIndex;
+        }
+        else if (arg === "--app-spec-id" || arg.startsWith("--app-spec-id=")) {
+            const result = readFlagValue(args, i, "--app-spec-id");
+            parsed.appSpecId = result.value;
+            i = result.nextIndex;
+        }
+        else if (arg === "--builtin" || arg.startsWith("--builtin=")) {
+            const result = readFlagValue(args, i, "--builtin");
+            parsed.appSpecId = result.value;
+            i = result.nextIndex;
+        }
+        else if (arg === "--from" || arg.startsWith("--from=")) {
+            const result = readFlagValue(args, i, "--from");
+            parsed.cloneFromInstanceId = result.value;
+            i = result.nextIndex;
+        }
+        else {
+            throw new Error(`Unknown option: ${arg}`);
+        }
+    }
+    parsed.id = positional[0];
+    if (positional.length > 1) {
+        throw new Error(`Unexpected argument: ${positional[1]}`);
+    }
+    return parsed;
 }
 function healthTargetsForTask(task) {
     if (!task?.health)
@@ -232,12 +334,6 @@ function fallbackTaskState(appStatus) {
         return "pending";
     return "unknown";
 }
-function resolveProvidePort(spec, provide) {
-    if (typeof provide?.port === "number")
-        return provide.port;
-    const serviceTask = spec.tasks.find((task) => (task.role ?? "service") === "service");
-    return serviceTask?.ports?.[0]?.port;
-}
 function provideAddress(port, path) {
     if (typeof port !== "number")
         return undefined;
@@ -249,7 +345,7 @@ function describeHealthTargets(targets) {
         .map((target) => `${target.method}${typeof target.port === "number" ? `:${target.port}` : ""}`)
         .join(",");
 }
-function enrichStatusForCli(status, spec) {
+function enrichStatusForCli(instanceId, status, spec) {
     const taskSpecs = new Map((spec?.tasks ?? []).map((task) => [task.name, task]));
     const taskNames = new Set([
         ...taskSpecs.keys(),
@@ -284,7 +380,7 @@ function enrichStatusForCli(status, spec) {
         };
     }
     const provides = (spec?.provides ?? []).map((provide) => {
-        const port = resolveProvidePort(spec, provide);
+        const port = resolveRuntimeCapabilityPort(instanceId, provide.capability) ?? undefined;
         return {
             capability: provide.capability,
             ...(typeof port === "number" ? { port } : {}),
@@ -331,12 +427,13 @@ function parseRemoteYamlUrl(value) {
 }
 const BUILTIN_INSTALL_ALIASES = {
     ollama: "ollama-binary.yaml",
+    searxng: "searxng-container.yaml",
 };
 async function loadBuiltinInstallYaml(source) {
     const normalizedSource = source.trim();
     if (!normalizedSource)
         return null;
-    const { listBuiltinAppSpecs } = await import("../services/app/app-manager.js");
+    const { listBuiltinAppSpecs } = await import("../services/app-common/service.js");
     const templates = listBuiltinAppSpecs();
     const normalizedWithoutExt = normalizedSource.replace(/\.ya?ml$/i, "");
     const aliasTarget = BUILTIN_INSTALL_ALIASES[normalizedWithoutExt] ?? BUILTIN_INSTALL_ALIASES[normalizedSource];
@@ -356,21 +453,8 @@ async function loadBuiltinInstallYaml(source) {
 async function loadInstallYaml(source) {
     const remoteUrl = parseRemoteYamlUrl(source);
     if (remoteUrl) {
-        let resp;
-        try {
-            resp = await fetch(remoteUrl, { signal: AbortSignal.timeout(30_000) });
-        }
-        catch (e) {
-            throw new Error(`Failed to download app YAML: ${e.message}`);
-        }
-        if (!resp.ok) {
-            throw new Error(`Failed to download app YAML: HTTP ${resp.status}`);
-        }
-        const body = await resp.text();
-        if (!body.trim()) {
-            throw new Error(`Downloaded app YAML is empty: ${remoteUrl}`);
-        }
-        return body;
+        const { loadRemoteAppSpecYaml } = await import("../services/app-common/remote-spec.js");
+        return loadRemoteAppSpecYaml(remoteUrl.toString(), { fieldName: "app install source URL" });
     }
     const builtinYaml = await loadBuiltinInstallYaml(source);
     if (builtinYaml) {
@@ -392,8 +476,8 @@ async function cmdList(args) {
     printManagedList("Managed Apps / Instances", items, c, log);
 }
 async function cmdShow(id) {
-    const { getApp, getInstance } = await import("../services/app/app-manager.js");
-    const app = getApp(id);
+    const { getInstanceInstallRecord, getInstance } = await import("../services/app-common/service.js");
+    const app = getInstanceInstallRecord(id);
     if (app) {
         console.log(JSON.stringify(app, null, 2));
         return;
@@ -408,7 +492,7 @@ async function cmdShow(id) {
 }
 async function cmdInstall(args) {
     const installSource = args[0];
-    let requestedAppId;
+    let requestedInstanceId;
     for (let index = 1; index < args.length; index += 1) {
         const value = args[index];
         if (value === "--sudo-password") {
@@ -417,20 +501,19 @@ async function cmdInstall(args) {
         }
         if (value.startsWith("--"))
             continue;
-        requestedAppId = value;
+        requestedInstanceId = value;
         break;
     }
     const yamlText = await loadInstallYaml(installSource);
-    const { installApp } = await import("../services/app/app-manager.js");
+    const { installInstance } = await import("../services/app-common/lifecycle-service.js");
     const sudoState = getCliSudoState(args);
     while (true) {
         try {
             const installOptions = sudoState.password ? { exec: { sudoPassword: sudoState.password } } : undefined;
             const result = installOptions
-                ? await installApp(yamlText, requestedAppId, installOptions)
-                : await installApp(yamlText, requestedAppId);
-            const installModeLabel = result.manifest.install_mode === "instance-dir" ? "instance" : "app";
-            log(c.green(`  ✓  Installed: ${result.manifest.id}  (${result.spec.name || ""} v${result.spec.version || "?"}, ${installModeLabel})`));
+                ? await installInstance(yamlText, requestedInstanceId, installOptions)
+                : await installInstance(yamlText, requestedInstanceId);
+            log(c.green(`  ✓  Installed: ${result.manifest.instanceId}  (${result.spec.name || ""} v${result.spec.version || "?"})`));
             return;
         }
         catch (err) {
@@ -443,14 +526,14 @@ async function cmdInstall(args) {
     }
 }
 async function cmdProvides(args) {
-    const { listProvidedCapabilities } = await import("../services/app/app-manager.js");
+    const { listProvidedCapabilities } = await import("../services/app-common/service.js");
     const provides = listProvidedCapabilities();
     if (args.includes("--json")) {
         console.log(JSON.stringify(provides, null, 2));
         return;
     }
     log("");
-    log(c.bold("  App Provides"));
+    log(c.bold("  Instance Provides"));
     log(c.dim("  ─────────────────────────────────────────────────────"));
     if (provides.length === 0) {
         log(c.dim("  (no app capabilities declared)"));
@@ -459,12 +542,12 @@ async function cmdProvides(args) {
     }
     const grouped = new Map();
     for (const provide of provides) {
-        const items = grouped.get(provide.appId) ?? [];
+        const items = grouped.get(provide.instanceId) ?? [];
         items.push(provide);
-        grouped.set(provide.appId, items);
+        grouped.set(provide.instanceId, items);
     }
-    for (const [appId, items] of grouped.entries()) {
-        log(`  ${c.cyan(appId)}`);
+    for (const [instanceId, items] of grouped.entries()) {
+        log(`  ${c.cyan(instanceId)}`);
         for (const provide of items) {
             const endpoint = provide.registeredAddress ?? provide.address ?? "-";
             const registration = provide.registered
@@ -475,14 +558,196 @@ async function cmdProvides(args) {
     }
     log("");
 }
+function parseOptionalFlag(args, flag) {
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (arg === flag || arg.startsWith(`${flag}=`)) {
+            const result = readFlagValue(args, index, flag);
+            return result.value;
+        }
+    }
+    return undefined;
+}
+async function cmdProviders(args) {
+    const { listConnectionProviders } = await import("../services/connections/admin.js");
+    const capability = parseOptionalFlag(args, "--capability");
+    const providers = await listConnectionProviders(capability);
+    if (args.includes("--json")) {
+        console.log(JSON.stringify(providers, null, 2));
+        return;
+    }
+    log("");
+    log(c.bold(capability ? `  Providers for ${capability}` : "  Capability Providers"));
+    log(c.dim("  ─────────────────────────────────────────────────────"));
+    if (providers.length === 0) {
+        log(c.dim("  (no matching providers registered)"));
+        log("");
+        return;
+    }
+    for (const provider of providers) {
+        const status = provider.status === "running"
+            ? c.green(provider.status)
+            : provider.status === "stopped"
+                ? c.dim(provider.status)
+                : c.yellow(provider.status);
+        log(`  ${c.cyan(provider.providerId).padEnd(28)} ${provider.capability.padEnd(20)} ${status}  ${provider.address}`);
+    }
+    log("");
+}
+function describeConnectionValue(value) {
+    if (value == null)
+        return c.dim("unbound");
+    if (typeof value !== "object")
+        return c.yellow("invalid");
+    const connection = value;
+    if (connection.kind === "single") {
+        return `${c.green("bound")} ${connection.providerId ?? "-"} / ${connection.capability ?? "-"}`;
+    }
+    if (connection.kind === "many") {
+        const count = Array.isArray(connection.providers) ? connection.providers.length : 0;
+        return `${c.green("bound")} ${count} provider(s)`;
+    }
+    return c.yellow("invalid");
+}
+async function cmdConnections(instanceId, args) {
+    const { getConnectionSummary, getConnectionStatus } = await import("../services/connections/admin.js");
+    const [summary, status] = await Promise.all([
+        getConnectionSummary(instanceId),
+        getConnectionStatus(instanceId),
+    ]);
+    if (args.includes("--json")) {
+        console.log(JSON.stringify({ ...summary, status }, null, 2));
+        return;
+    }
+    log("");
+    log(`  ${c.bold("Instance:")}    ${c.cyan(instanceId)}`);
+    log(`  ${c.bold("Connections:")} ${status.state === "ok" ? c.green(status.state) : status.state === "empty" ? c.dim(status.state) : c.yellow(status.state)}`);
+    if (summary.requires.length === 0) {
+        log(c.dim("  (this app does not require external capabilities)"));
+        log("");
+        return;
+    }
+    for (const req of summary.requires) {
+        const pending = summary.pending.find((item) => item.slot === req.inject_as);
+        const connection = summary.connections[req.inject_as];
+        const required = req.required ? "required" : "optional";
+        const pendingText = pending ? `  ${c.yellow(pending.reason)}` : "";
+        log(`  ${c.bold(req.inject_as.padEnd(18))} ${req.capability.padEnd(16)} ${required.padEnd(8)} ${describeConnectionValue(connection)}${pendingText}`);
+        if (req.candidates.length > 0) {
+            const candidates = req.candidates
+                .slice(0, 4)
+                .map((candidate) => `${candidate.providerId}/${candidate.capability}:${candidate.status}`)
+                .join(", ");
+            const more = req.candidates.length > 4 ? ` +${req.candidates.length - 4} more` : "";
+            log(c.dim(`    candidates: ${candidates}${more}`));
+        }
+        else {
+            log(c.dim("    candidates: none"));
+        }
+    }
+    log("");
+}
+function parseBindArgs(args) {
+    const parsed = {};
+    const positional = [];
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (!arg.startsWith("--")) {
+            positional.push(arg);
+            continue;
+        }
+        if (arg === "--slot" || arg.startsWith("--slot=")) {
+            const result = readFlagValue(args, index, "--slot");
+            parsed.slot = result.value;
+            index = result.nextIndex;
+        }
+        else if (arg === "--provider" || arg.startsWith("--provider=")) {
+            const result = readFlagValue(args, index, "--provider");
+            parsed.providerId = result.value;
+            index = result.nextIndex;
+        }
+        else if (arg === "--capability" || arg.startsWith("--capability=")) {
+            const result = readFlagValue(args, index, "--capability");
+            parsed.capability = result.value;
+            index = result.nextIndex;
+        }
+        else if (arg === "--model" || arg.startsWith("--model=")) {
+            const result = readFlagValue(args, index, "--model");
+            parsed.selectedModelId = result.value;
+            index = result.nextIndex;
+        }
+        else {
+            throw new Error(`Unknown option: ${arg}`);
+        }
+    }
+    parsed.instanceId = positional[0];
+    if (positional.length > 1)
+        throw new Error(`Unexpected argument: ${positional[1]}`);
+    return parsed;
+}
+async function cmdBind(args) {
+    const parsed = parseBindArgs(args);
+    if (!parsed.instanceId || !parsed.slot || !parsed.providerId || !parsed.capability) {
+        throw new Error("Usage: jishushell app bind <instance-id> --slot <slot> --provider <provider-instance-id> --capability <capability>");
+    }
+    const { bindConnection } = await import("../services/connections/admin.js");
+    await bindConnection({
+        instanceId: parsed.instanceId,
+        slot: parsed.slot,
+        providerId: parsed.providerId,
+        capability: parsed.capability,
+        ...(parsed.selectedModelId ? { selectedModelId: parsed.selectedModelId } : {}),
+    });
+    log(c.green(`  ✓  Bound ${parsed.instanceId}:${parsed.slot} to ${parsed.providerId}/${parsed.capability}`));
+}
+async function cmdUnbind(instanceId, args) {
+    const slot = parseOptionalFlag(args, "--slot");
+    if (!slot) {
+        throw new Error("Usage: jishushell app unbind <instance-id> --slot <slot>");
+    }
+    const { unbindConnection } = await import("../services/connections/admin.js");
+    await unbindConnection({ instanceId, slot });
+    log(c.green(`  ✓  Unbound ${instanceId}:${slot}`));
+}
+async function cmdConfig(args) {
+    const subcmd = args[0];
+    const instanceId = args[1];
+    if (!subcmd || !instanceId) {
+        throw new Error("Usage: jishushell app config <get|set|meta> <instance-id> [key=value]");
+    }
+    if (subcmd === "get") {
+        const { readAppConfig } = await import("../services/instances/config-admin.js");
+        const config = await readAppConfig(instanceId);
+        console.log(JSON.stringify(config, null, 2));
+        return;
+    }
+    if (subcmd === "meta") {
+        const { getAppConfigMeta } = await import("../services/instances/config-admin.js");
+        const meta = getAppConfigMeta(instanceId);
+        console.log(JSON.stringify(meta, null, 2));
+        return;
+    }
+    if (subcmd === "set") {
+        const assignment = args[2];
+        if (!assignment) {
+            throw new Error("Usage: jishushell app config set <instance-id> <key=value>");
+        }
+        const { setAppConfigValue } = await import("../services/instances/config-admin.js");
+        await setAppConfigValue(instanceId, assignment);
+        log(c.green(`  ✓  Updated config for ${instanceId}`));
+        return;
+    }
+    throw new Error("Usage: jishushell app config <get|set|meta> <instance-id> [key=value]");
+}
 async function cmdUninstall(id, args = []) {
-    const { uninstallAppTask, getApp, getInstance } = await import("../services/app/app-manager.js");
-    if (getApp(id)) {
-        await runManagedUninstallTask((exec) => exec ? uninstallAppTask(id, exec) : uninstallAppTask(id), `Uninstalled: ${id}`, getCliSudoState(args));
+    const { uninstallInstanceTask } = await import("../services/app-common/lifecycle-service.js");
+    const { getInstanceInstallRecord, getInstance } = await import("../services/app-common/service.js");
+    if (getInstanceInstallRecord(id)) {
+        await runManagedUninstallTask((exec) => exec ? uninstallInstanceTask(id, exec) : uninstallInstanceTask(id), `Uninstalled: ${id}`, getCliSudoState(args));
         return;
     }
     if (getInstance(id)) {
-        const { deleteInstance } = await import("../services/instance-manager.js");
+        const { deleteInstance } = await import("../services/instances/manager.js");
         const deleteResult = await deleteInstance(id);
         if (!deleteResult.ok) {
             throw new Error(`Failed to uninstall instance '${id}'`);
@@ -499,13 +764,14 @@ async function cmdUninstallAll(args = []) {
         log(c.dim("  (no managed apps or instances to uninstall)"));
         return;
     }
-    const { uninstallAppTask } = await import("../services/app/app-manager.js");
-    const { deleteInstance } = await import("../services/instance-manager.js");
+    const { uninstallInstanceTask } = await import("../services/app-common/lifecycle-service.js");
+    const { getInstanceInstallRecord } = await import("../services/app-common/service.js");
+    const { deleteInstance } = await import("../services/instances/manager.js");
     const errors = [];
     const sudoState = getCliSudoState(args);
     for (const item of items) {
         try {
-            if (item.install_mode === "legacy-instance") {
+            if (!getInstanceInstallRecord(item.id)) {
                 const deleteResult = await deleteInstance(item.id);
                 if (!deleteResult.ok) {
                     throw new Error(`Failed to uninstall instance '${item.id}'`);
@@ -513,12 +779,12 @@ async function cmdUninstallAll(args = []) {
             }
             else {
                 const started = sudoState.password
-                    ? uninstallAppTask(item.id, { sudoPassword: sudoState.password })
-                    : uninstallAppTask(item.id);
+                    ? uninstallInstanceTask(item.id, { sudoPassword: sudoState.password })
+                    : uninstallInstanceTask(item.id);
                 if (!started.ok) {
                     const startedMessage = started.error || `Failed to uninstall '${item.id}'`;
                     if (isSudoPasswordError(startedMessage) && await promptForCliSudoPassword(sudoState)) {
-                        const retried = uninstallAppTask(item.id, { sudoPassword: sudoState.password });
+                        const retried = uninstallInstanceTask(item.id, { sudoPassword: sudoState.password });
                         if (!retried.ok) {
                             throw new Error(formatSudoHint(retried.error || `Failed to uninstall '${item.id}'`, sudoState));
                         }
@@ -535,7 +801,7 @@ async function cmdUninstallAll(args = []) {
                 if (taskResult.status === "error") {
                     const taskMessage = taskResult.message || `Failed to uninstall '${item.id}'`;
                     if (isSudoPasswordError(taskMessage) && await promptForCliSudoPassword(sudoState)) {
-                        const retried = uninstallAppTask(item.id, { sudoPassword: sudoState.password });
+                        const retried = uninstallInstanceTask(item.id, { sudoPassword: sudoState.password });
                         if (!retried.ok) {
                             throw new Error(formatSudoHint(retried.error || `Failed to uninstall '${item.id}'`, sudoState));
                         }
@@ -561,125 +827,116 @@ async function cmdUninstallAll(args = []) {
         process.exitCode = 1;
     }
 }
-async function cmdCreateInstance(appId, instanceId, name) {
-    const { getApp, installApp, updateInstance } = await import("../services/app/app-manager.js");
-    const { resolveConnections, resolvedToLegacyEnv } = await import("../services/connection-resolver.js");
-    const appData = getApp(appId);
-    if (!appData) {
-        log(c.red(`  ✗  App "${appId}" not found.`));
-        process.exitCode = 1;
-        return;
-    }
-    // PR 3 sub-step 3e: switch CLI to resolveConnections (preCreate). Pending
-    // requires are printed so the user can see what still needs binding.
-    let resolvedEnv = {};
+async function cmdCloneInstance(sourceInstanceId, instanceId, name, description = "") {
+    const { cloneInstance, isInstanceCloneError, } = await import("../services/instances/clone.js");
     try {
-        const { resolved, pending } = resolveConnections(appData.spec, { connections: {} }, "preCreate");
-        resolvedEnv = resolvedToLegacyEnv(resolved);
-        if (pending.length > 0) {
-            log(c.yellow(`  ⚠  ${pending.length} pending connection(s):`));
-            for (const p of pending) {
-                log(c.yellow(`     - ${p.slot} (${p.capability}): ${p.reason}`));
+        const result = await cloneInstance({
+            sourceInstanceId,
+            targetId: instanceId,
+            name,
+            description,
+        });
+        if (result.pending && result.pending.length > 0) {
+            log(c.yellow(`  ⚠  ${result.pending.length} pending connection(s):`));
+            for (const pending of result.pending) {
+                log(c.yellow(`     - ${pending.slot} (${pending.capability}): ${pending.reason}`));
             }
         }
     }
     catch (e) {
+        if (isInstanceCloneError(e)) {
+            log(c.red(`  ✗  ${e.message}`));
+            process.exitCode = 1;
+            return;
+        }
         log(c.red(`  ✗  ${e.message}`));
         process.exitCode = 1;
         return;
     }
-    const specWithEnv = Object.keys(resolvedEnv).length > 0
-        ? {
-            ...appData.spec,
-            app_id: appData.manifest.id,
-            tasks: appData.spec.tasks.map((t) => t.role === "service" ? { ...t, env: { ...t.env, ...resolvedEnv } } : t),
-        }
-        : { ...appData.spec, app_id: appData.manifest.id };
-    const rawYaml = rewriteInstalledAppYaml(stringify({
-        ...specWithEnv,
-        name,
-    }), appData.manifest.id, instanceId);
-    await installApp(rawYaml, instanceId, {
-        bootstrap: {
-            name,
-            description: "",
-        },
-    });
-    updateInstance(instanceId, name, "");
-    log(c.green(`  ✓  Created application "${instanceId}" from app "${appId}"`));
-}
-async function cmdCopy(sourceId) {
-    const { copyApp } = await import("../services/app/app-manager.js");
-    const result = await copyApp(sourceId);
-    log(c.green(`  ✓  Copied ${sourceId}  →  ${result.manifest.id}`));
+    log(c.green(`  ✓  Cloned instance "${sourceInstanceId}" to "${instanceId}"`));
 }
-async function cmdStart(appId) {
-    ensureNomadToken();
-    const { getApp, startAppTask } = await import("../services/app/app-manager.js");
-    const app = getApp(appId);
-    if (app) {
-        await runManagedAppTask(() => startAppTask(appId), `Started: ${app.spec.name || readInstanceMeta(appId)?.name || appId}`);
-        return;
+async function cmdCreate(args) {
+    const parsed = parseCreateArgs(args);
+    if (!parsed.id || !parsed.name) {
+        throw new Error("Usage: jishushell app create <id> --name <name>");
     }
-    const result = await startNomadJobInstance(appId);
-    if (result.ok) {
-        log(c.green(`  ✓  Started: ${readInstanceMeta(appId)?.name || appId}`));
+    if (parsed.cloneFromInstanceId) {
+        if (parsed.appSpecId) {
+            throw new Error("app create --from cannot be combined with --builtin or --app-spec-id");
+        }
+        await cmdCloneInstance(parsed.cloneFromInstanceId, parsed.id, parsed.name, parsed.description || "");
         return;
     }
-    log(c.red(`  ✗  ${result.error || "Start failed"}`));
-    process.exitCode = 1;
+    const { createInstance } = await import("../services/instances/admin.js");
+    const result = await createInstance({
+        id: parsed.id,
+        name: parsed.name,
+        ...(parsed.description != null ? { description: parsed.description } : {}),
+        ...(parsed.appSpecId ? { app_spec_id: parsed.appSpecId } : {}),
+    });
+    console.log(JSON.stringify(result, null, 2));
 }
-async function cmdStop(appId, purge) {
+async function cmdStart(instanceId) {
     ensureNomadToken();
-    const { getApp, stopAppTask } = await import("../services/app/app-manager.js");
-    const app = getApp(appId);
-    if (app) {
-        await runManagedAppTask(() => stopAppTask(appId, purge), `Stopped: ${app.spec.name || readInstanceMeta(appId)?.name || appId}${purge ? " (purged)" : ""}`);
-        return;
-    }
-    const result = await stopNomadJobInstance(appId, purge);
-    if (result.ok) {
-        log(c.green(`  ✓  Stopped: ${readInstanceMeta(appId)?.name || appId}${purge ? " (purged)" : ""}`));
+    const { startInstanceTask } = await import("../services/app-common/lifecycle-service.js");
+    const { getInstanceInstallRecord, getInstance } = await import("../services/app-common/service.js");
+    const app = getInstanceInstallRecord(instanceId);
+    const instance = getInstance(instanceId);
+    if (app || instance) {
+        const ok = await runManagedAppTask(() => startInstanceTask(instanceId), `Started: ${app?.spec.name || readInstanceMeta(instanceId)?.name || instanceId}`);
+        if (ok) {
+            markRuntimeRepairRestartApplied(instanceId);
+        }
         return;
     }
-    log(c.red(`  ✗  ${result.error || "Stop failed"}`));
-    process.exitCode = 1;
+    await runLegacyRawRuntimeStart(instanceId);
 }
-async function cmdRestart(appId) {
+async function cmdStop(instanceId, purge) {
     ensureNomadToken();
-    const { getApp, restartAppTask } = await import("../services/app/app-manager.js");
-    const app = getApp(appId);
-    if (app) {
-        await runManagedAppTask(() => restartAppTask(appId), `Restarted: ${app.spec.name || readInstanceMeta(appId)?.name || appId}`);
+    const { stopInstanceTask } = await import("../services/app-common/lifecycle-service.js");
+    const { getInstanceInstallRecord, getInstance } = await import("../services/app-common/service.js");
+    const app = getInstanceInstallRecord(instanceId);
+    const instance = getInstance(instanceId);
+    if (app || instance) {
+        await runManagedAppTask(() => stopInstanceTask(instanceId, purge), `Stopped: ${app?.spec.name || readInstanceMeta(instanceId)?.name || instanceId}${purge ? " (purged)" : ""}`);
         return;
     }
-    const result = await restartNomadJobInstance(appId);
-    if (result.ok) {
-        log(c.green(`  ✓  Restarted: ${readInstanceMeta(appId)?.name || appId}`));
+    await runLegacyRawRuntimeStop(instanceId, purge);
+}
+async function cmdRestart(instanceId) {
+    ensureNomadToken();
+    const { restartInstanceTask } = await import("../services/app-common/lifecycle-service.js");
+    const { getInstanceInstallRecord, getInstance } = await import("../services/app-common/service.js");
+    const app = getInstanceInstallRecord(instanceId);
+    const instance = getInstance(instanceId);
+    if (app || instance) {
+        const ok = await runManagedAppTask(() => restartInstanceTask(instanceId), `Restarted: ${app?.spec.name || readInstanceMeta(instanceId)?.name || instanceId}`);
+        if (ok) {
+            markRuntimeRepairRestartApplied(instanceId);
+        }
         return;
     }
-    log(c.red(`  ✗  ${result.error || "Restart failed"}`));
-    process.exitCode = 1;
+    await runLegacyRawRuntimeRestart(instanceId);
 }
-async function cmdStatus(appId, json) {
+async function cmdStatus(instanceId, json) {
     ensureNomadToken();
-    const { getApp, getAppStatus, getInstance } = await import("../services/app/app-manager.js");
-    const app = getApp(appId);
+    const { getInstanceInstallRecord, getInstanceInstallRecordStatus, getInstance } = await import("../services/app-common/service.js");
+    const app = getInstanceInstallRecord(instanceId);
     if (!app) {
-        const instance = getInstance(appId);
+        const instance = getInstance(instanceId);
         if (!instance) {
-            log(c.red(`  ✗  App/instance "${appId}" not found.`));
+            log(c.red(`  ✗  Instance "${instanceId}" not found.`));
             process.exitCode = 1;
             return;
         }
-        const status = await getInstanceStatus(appId);
+        const status = await getInstanceStatus(instanceId);
         if (json) {
-            console.log(JSON.stringify({ id: appId, name: instance.name, ...status }, null, 2));
+            console.log(JSON.stringify({ id: instanceId, name: instance.name, ...status }, null, 2));
             return;
         }
         const upStr = status.uptime ? `${Math.floor(status.uptime / 3600)}h ${Math.floor((status.uptime % 3600) / 60)}m` : "—";
         log("");
-        log(`  ${c.bold("Job:")} ${c.cyan(instance.name || appId)}  ${c.dim(`(${appId})`)}`);
+        log(`  ${c.bold("Job:")} ${c.cyan(instance.name || instanceId)}  ${c.dim(`(${instanceId})`)}`);
         log(`  ${c.bold("Status:")} ${status.status === "running" ? c.green(status.status) : status.status}`);
         log(`  ${c.bold("Uptime:")} ${upStr}`);
         if (status.memory_mb)
@@ -691,10 +948,10 @@ async function cmdStatus(appId, json) {
         log("");
         return;
     }
-    const status = await getAppStatus(appId);
-    const enriched = enrichStatusForCli(status, app.spec);
+    const status = await getInstanceInstallRecordStatus(instanceId);
+    const enriched = enrichStatusForCli(instanceId, status, app.spec);
     if (json) {
-        console.log(JSON.stringify({ id: appId, ...status, tasks: enriched.tasks, provides: enriched.provides }, null, 2));
+        console.log(JSON.stringify({ id: instanceId, ...status, tasks: enriched.tasks, provides: enriched.provides }, null, 2));
         return;
     }
     const stColor = status.status === "running" ? c.green
@@ -702,7 +959,7 @@ async function cmdStatus(appId, json) {
             : status.status === "pending" ? c.yellow
                 : c.red;
     log("");
-    log(`  ${c.bold("App:")}    ${c.cyan(appId)}`);
+    log(`  ${c.bold("Instance:")} ${c.cyan(instanceId)}`);
     log(`  ${c.bold("Status:")} ${stColor(status.status)}`);
     if (status.uptime != null)
         log(`  ${c.bold("Uptime:")} ${status.uptime}s`);
@@ -731,27 +988,48 @@ async function cmdStatus(appId, json) {
         log(c.red(`  ${status.error}`));
     log("");
 }
-async function cmdLogs(appId, args) {
+async function cmdLogs(instanceId, args) {
     ensureNomadToken();
-    const { getApp, getAppLogs } = await import("../services/app/app-manager.js");
+    const { getInstanceInstallRecord, getInstanceInstallRecordLogs } = await import("../services/app-common/service.js");
     const taskArg = args.find((a) => !a.startsWith("--"));
     const lines = parseFlag(args, "--lines", 200);
     const logType = args.includes("--stdout") ? "stdout" : "stderr";
-    const logLines = getApp(appId)
-        ? await getAppLogs(appId, taskArg ?? "", lines, logType)
-        : await getInstanceLogs(appId, lines, logType);
+    const logLines = getInstanceInstallRecord(instanceId)
+        ? await getInstanceInstallRecordLogs(instanceId, taskArg ?? "", lines, logType)
+        : await getInstanceLogs(instanceId, lines, logType);
     if (logLines.length === 0) {
         log(c.dim("  (no logs)"));
         return;
     }
     process.stdout.write(logLines.join("\n") + "\n");
 }
-async function cmdExec(appId, command) {
+function parseExecArgs(args) {
+    const dashDash = args.indexOf("--");
+    if (dashDash < 0)
+        return { command: [], error: "missing command separator" };
+    const options = args.slice(0, dashDash);
+    const command = args.slice(dashDash + 1);
+    let user;
+    for (let i = 0; i < options.length; i += 1) {
+        const arg = options[i];
+        if (arg === "--user" || arg === "-u") {
+            const value = options[i + 1];
+            if (!value || value.startsWith("-"))
+                return { command, error: `${arg} requires a value` };
+            user = value;
+            i += 1;
+            continue;
+        }
+        return { command, error: `unknown exec option: ${arg}` };
+    }
+    return { command, user };
+}
+async function cmdExec(instanceId, command, options = {}) {
     ensureNomadToken();
-    const { getApp, execInApp } = await import("../services/app/app-manager.js");
-    const result = getApp(appId)
-        ? await execInApp(appId, command)
-        : await execInInstance(appId, command);
+    const { getInstanceInstallRecord, execInApp } = await import("../services/app-common/service.js");
+    const result = getInstanceInstallRecord(instanceId)
+        ? await execInApp(instanceId, command, undefined, options)
+        : await execInInstance(instanceId, command, undefined, options);
     if (result.stdout)
         process.stdout.write(result.stdout);
     if (result.stderr)
@@ -769,6 +1047,21 @@ export async function run(rest) {
         else if (appCmd === "provides") {
             await cmdProvides(rest.slice(1));
         }
+        else if (appCmd === "providers") {
+            await cmdProviders(rest.slice(1));
+        }
+        else if (appCmd === "connections" && rest[1]) {
+            await cmdConnections(rest[1], rest.slice(2));
+        }
+        else if (appCmd === "bind") {
+            await cmdBind(rest.slice(1));
+        }
+        else if (appCmd === "unbind" && rest[1]) {
+            await cmdUnbind(rest[1], rest.slice(2));
+        }
+        else if (appCmd === "config") {
+            await cmdConfig(rest.slice(1));
+        }
         else if (appCmd === "show" && rest[1]) {
             await cmdShow(rest[1]);
         }
@@ -781,18 +1074,8 @@ export async function run(rest) {
         else if (appCmd === "uninstall" && rest[1]) {
             await cmdUninstall(rest[1], rest.slice(2));
         }
-        else if (appCmd === "create-instance" && rest[1]) {
-            const appId = rest[1];
-            const instanceId = rest[2];
-            const name = rest[3] || instanceId;
-            if (!instanceId) {
-                console.error("Usage: jishushell app create-instance <app-id> <instance-id> [name]");
-                process.exit(1);
-            }
-            await cmdCreateInstance(appId, instanceId, name);
-        }
-        else if (appCmd === "copy" && rest[1]) {
-            await cmdCopy(rest[1]);
+        else if (appCmd === "create") {
+            await cmdCreate(rest.slice(1));
         }
         else if (appCmd === "start" && rest[1]) {
             await cmdStart(rest[1]);
@@ -810,13 +1093,14 @@ export async function run(rest) {
             await cmdLogs(rest[1], rest.slice(2));
         }
         else if (appCmd === "exec" && rest[1]) {
-            const dashDash = rest.indexOf("--");
-            const execCmd = dashDash >= 0 ? rest.slice(dashDash + 1) : [];
-            if (execCmd.length === 0) {
-                console.error("Usage: jishushell app exec <app-id> -- <command...>");
+            const parsed = parseExecArgs(rest.slice(2));
+            if (parsed.command.length === 0 || parsed.error) {
+                if (parsed.error && parsed.error !== "missing command separator")
+                    console.error(parsed.error);
+                console.error("Usage: jishushell app exec <instance-id> [--user <user>|-u <user>] -- <command...>");
                 process.exit(1);
             }
-            await cmdExec(rest[1], execCmd);
+            await cmdExec(rest[1], parsed.command, { user: parsed.user });
         }
         else if (appCmd === "help" || appCmd === "--help" || appCmd === "-h") {
             printHelp();
@@ -839,38 +1123,56 @@ export async function dispatch(argv) {
     return true;
 }
 export function brief() {
-    return "  app <install|list|provides|show|uninstall|copy|start|stop|restart|status|logs|exec>  App/实例统一管理";
+    return "  app <create|install|providers|connections|bind|config|start|status>  实例与 AppSpec 安装管理";
 }
 export function printHelp() {
     console.log(`
 Usage: jishushell app <command> [options]
 
 Commands:
-  list [--json]                                     列出统一受管列表（apps 下已安装应用 + instances 下遗留实例）
-  provides [--json]                                 列出已安装 App 声明/注册的能力
-  show <id>                                         查看 App 或实例详情（JSON）
-  install <yaml-file|https-url|builtin-id> [app-id] [--sudo-password <password>]
-                                                    从本地、HTTPS 或内置模板安装 App，可选指定安装 id
-  uninstall <app-id> [--sudo-password <password>]   卸载单个 App 或实例（停止 + 删除目录）
-  uninstall --all [--sudo-password <password>]      卸载全部 App 与实例
-  create-instance <app-id> <inst-id> [name]         从 App 创建实例（Agent 通道由 spec.agentType 决定）
-  copy <app-id>                                     复制 App 实例（singleInstance 不可 copy）
-  start <id>                                        启动 App 或实例
-  stop <id> [--purge]                               停止 App 或实例（--purge 同时清除 Nomad job）
-  restart <id>                                      重启 App 或实例
-  status <id> [--json]                              查看 App 或实例状态
+  create <id> --name <name> [--builtin <builtin-id>]
+                                                    按 builtin AppSpec 创建实例（默认 builtin=openclaw-container）
+  create <id> --name <name> --from <instance-id>   从已有实例克隆一个新实例
+  list [--json]                                     列出受管实例
+  provides [--json]                                 列出实例声明/注册的能力
+  providers [--capability <name>] [--json]          列出可绑定 provider
+  connections <instance-id> [--json]                查看实例依赖能力与绑定状态
+  bind <instance-id> --slot <slot> --provider <id> --capability <capability>
+                                                    绑定实例依赖能力到 provider 实例
+  unbind <instance-id> --slot <slot>                解除实例能力绑定
+  config get <instance-id>                          查看实例配置
+  config set <instance-id> <key=value>              修改实例配置字段
+  config meta <instance-id>                         查看实例配置元信息
+  show <id>                                         查看实例详情（JSON）
+  install <yaml-file|https-url|builtin-id> [instance-id] [--sudo-password <password>]
+                                                    从本地、HTTPS 或内置 AppSpec 安装实例，可选指定实例 id
+  uninstall <instance-id> [--sudo-password <password>]
+                                                    卸载单个实例（停止 + 删除目录）
+  uninstall --all [--sudo-password <password>]      卸载全部实例
+  start <id>                                        启动实例
+  stop <id> [--purge]                               停止实例（--purge 同时清除 Nomad job）
+  restart <id>                                      重启实例
+  status <id> [--json]                              查看实例状态
   logs <id> [<task>] [--lines N] [--stdout]         查看日志（默认 stderr）
-  exec <id> -- <cmd...>                             在 App 或实例内执行命令
+  exec <id> -- <cmd...>                             在实例内执行命令
   help                                              显示此帮助
 
 Examples:
+  jishushell app create my-openclaw --name MyOpenClaw
+  jishushell app create my-hermes --name MyHermes --builtin hermes-container
+  jishushell app create my-ollama --name MyOllama --builtin ollama-with-hollama-binary
+  jishushell app create my-searxng-2 --name MySearxng2 --from my-searxng
   jishushell app install ./apps/ollama-with-hollama-binary.yaml
   jishushell app install ./apps/ollama-with-hollama-binary.yaml ollama-local
   jishushell app install https://example.com/apps/ollama-with-hollama-binary.yaml
   jishushell app install ollama
   jishushell app list
   jishushell app provides
-  jishushell app copy ollama-1
+  jishushell app providers --capability search
+  jishushell app connections my-openclaw
+  jishushell app bind my-openclaw --slot search --provider searxng --capability search-searxng
+  jishushell app config get my-openclaw
+  jishushell app config set my-openclaw x-jishushell.proxy.upstream.providerId=ollama
   jishushell app start searxng-container
   jishushell app status ollama
   jishushell app logs ollama --lines 100