jishushell 0.6.5 → 0.7.3

package/dist/types.d.ts

@@ -1,5 +1,11 @@
 import type { LlmProvider } from "./services/llm-proxy/providers.js";
+import type { CapabilityInterface, CapabilityKind } from "./services/capabilities/contract.js";
 export interface InstanceStatus {
+    /**
+     * Raw runtime/backend status. Runtime drivers may use backend-specific
+     * strings here; product status must be translated into AppInstanceStatus
+     * before persistence.
+     */
     status: "running" | "pending" | "stopped" | "failed" | string;
     pid: number | null;
     uptime: number | null;
@@ -12,20 +18,20 @@ export interface ServiceResult {
     warning?: string;
     pid?: number;
     /**
-     * startInstance-only: tag identifying which phase of the start pipeline
+     * Lifecycle start/restart: tag identifying which phase of the start pipeline
      * produced the error. Present on every error result returned by
-     * nomad-manager.startInstance so callers (routes, tests, logs) can
+     * the Nomad driver's start operation so callers (routes, tests, logs) can
      * distinguish where the failure happened.
      */
-    phase?: "running_check" | "home_conflict" | "port_alloc" | "pre_start_hook" | "submit";
-    /** Adapter signaled an async background build; poll taskId for progress. */
+    phase?: "running_check" | "home_conflict" | "port_alloc" | "pre_start_hook" | "submit" | "start.waitReady" | "restart.waitReady" | "restart.waitStop" | "stop.waitStop";
+    /** Integration signaled an async background build; poll taskId for progress. */
     building?: boolean;
     taskId?: string;
     /** Nomad alloc ID returned by waitForRunning / restartInstance. */
     alloc_id?: string;
     /** Nomad eval ID returned by submitJob. */
     eval_id?: string;
-    /** Port allocation metadata from adapters (process-manager / nomad-manager). */
+    /** Port allocation metadata returned by the Nomad runtime driver. */
     port_allocation?: unknown;
     /**
      * Stable error code for callers that prefer machine-readable tags over
@@ -39,21 +45,25 @@ export interface ExecResult {
     stderr: string;
     exitCode: number;
 }
+export interface ExecOptions {
+    timeoutMs?: number;
+    user?: string;
+}
 export interface ServiceManager {
     getStatus(id: string): Promise<InstanceStatus>;
-    startInstance(id: string): Promise<ServiceResult>;
-    stopInstance(id: string, purge?: boolean): Promise<ServiceResult>;
-    restartInstance(id: string): Promise<ServiceResult>;
     getLogs(id: string, lines?: number, logType?: string): Promise<string[]> | string[];
     /** Run a command inside the running instance (docker exec or direct exec). */
-    exec(id: string, command: string[], timeoutMs?: number): Promise<ExecResult>;
+    exec(id: string, command: string[], timeoutMs?: number, options?: ExecOptions): Promise<ExecResult>;
 }
 /**
- * Runtime catalog entry stored in core.json.runtime_catalog.<agentType>.
- * See docs/multi-agent-runtime-generalization-plan.md §32.1 (digest pin) and §32.3 (MVP shape).
- * Fields are camelCase per §8 naming convention.
+ * Integration runtime installation record stored in the historical
+ * `core.json.runtime_catalog.<kind>` field.
+ *
+ * The on-disk key intentionally remains `runtime_catalog` for upgrade
+ * compatibility. New code should treat the value as integration-owned setup
+ * state, not as instance runtime truth or a public catalog.
  */
-export interface RuntimeCatalogEntry {
+export interface IntegrationRuntimeEntry {
     defaultImage: string;
     defaultImageDigest?: string;
     shimPath?: string;
@@ -66,23 +76,23 @@ export interface RuntimeCatalogEntry {
     };
     allowDockerSock?: boolean;
 }
-export interface RuntimeCatalog {
-    openclaw?: RuntimeCatalogEntry;
-    hermes?: RuntimeCatalogEntry;
-    [agentType: string]: RuntimeCatalogEntry | undefined;
+export interface IntegrationRuntimeRegistry {
+    openclaw?: IntegrationRuntimeEntry;
+    hermes?: IntegrationRuntimeEntry;
+    [kind: string]: IntegrationRuntimeEntry | undefined;
 }
 export interface CoreConfig {
     service_manager?: "process" | "nomad";
     nomad_driver?: "docker";
     nomad_token?: string;
     allowed_origins?: string[];
-    /** Per-runtime catalog. OpenClaw and Hermes both live here. */
-    runtime_catalog?: RuntimeCatalog;
+    /** Historical persisted key for integration runtime installation records. */
+    runtime_catalog?: IntegrationRuntimeRegistry;
     /**
      * Version of the `runtime_catalog` schema this core.json was last written
      * against. Core code advertises the highest version it understands via
-     * `CURRENT_CATALOG_SCHEMA_VERSION`; a newer value here (written by a newer
-     * core) triggers a startup warning and disables catalog mutations so a
+     * `CURRENT_INTEGRATION_RUNTIME_SCHEMA_VERSION`; a newer value here (written
+     * by a newer core) triggers a startup warning and disables mutations so a
      * downgraded core cannot silently corrupt structure it doesn't recognize.
      */
     runtime_catalog_schema_version?: number;
@@ -180,6 +190,29 @@ export interface AppTaskVolume {
     target: string;
     readonly?: boolean;
 }
+export interface AppStorageSpec {
+    class: "managed" | "data" | "cache";
+}
+export interface AppTaskMount {
+    storage: string;
+    target: string;
+    readonly?: boolean;
+}
+export interface AppNetworkSpec {
+    /**
+     * Put container tasks on an app-scoped Docker user-defined bridge network.
+    * Runtime infrastructure owns ensuring the network exists before Nomad starts
+    * the tasks; AppSpecs only declare the network intent. Existing same-name
+    * Docker bridge networks are reused, same-name non-bridge networks are
+    * replaced, and uninstall removes the app-scoped network by exact name.
+    * Container tasks are registered with their task name as a Docker network
+    * alias, which lets peer containers resolve `database`, `redis`, etc.
+    * without publishing those ports on the host.
+     */
+    mode: "docker-bridge";
+    /** Defaults to `jishushell-${instance.id}` after token materialization. */
+    name?: string;
+}
 export interface AppTask {
     name: string;
     role?: AppTaskRole;
@@ -195,13 +228,15 @@ export interface AppTask {
     after?: string[];
     /** Volumes: string format "src:dest[:ro]" or object { source, target, readonly? } */
     volumes?: Array<string | AppTaskVolume>;
+    /** Canonical storage mount contract from docs/core-app-architecture.md. */
+    mounts?: AppTaskMount[];
     /**
      * Container task user spec. Format: "uid:gid" (numeric) or "uid". Special
      * value "host" resolves to the panel process's `process.getuid()`:`getgid()`
      * at job-build time — keeps bind-mounted data dirs writable by the panel
      * user (typically `pi`) without forcing the container to run as root and
      * without needing `chown`/`CAP_DAC_OVERRIDE` gymnastics. Mirrors how the
-     * hermes / openclaw adapters set `User`. When omitted on container tasks
+     * Hermes / OpenClaw integrations set `User`. When omitted on container tasks
      * the unified builder falls back to "host" by default.
      */
     user?: string;
@@ -237,26 +272,78 @@ export interface AppTerminalConfig {
 /**
  * Health-probe spec attached to a provide. When omitted, the prober derives
  * a default strategy from `protocol` (§5.6: http→HEAD, ws/tcp→connect,
- * mcp→initialize, terminal→no-op).
+ * terminal→no-op).
  */
 export interface ProvideHealthSpec {
-    kind?: "http" | "tcp" | "mcp" | "none";
+    kind?: "http" | "tcp" | "none";
     /** HTTP path to probe (defaults to "/"). Ignored for non-http kinds. */
     path?: string;
     /** Custom port to probe; defaults to the provide's resolved hostPort. */
     port?: number;
 }
 export interface AppProvide {
+    /**
+     * Provider-local capability id, e.g. "ollama" or "searxng".
+     * This is display/metadata for a provider's own capability entry; it is not
+     * a matching key and must not be treated as the LLM engine/provider kind.
+     */
+    id?: string;
+    /**
+     * Stable capability key used in URLs, registry buckets, and exact requires.
+     * Concrete names such as `llm-ollama` match only the same capability. Use a
+     * category token in AppRequire.capability (`llm`, `search`, ...) when the
+     * consumer intentionally wants kind/interface contract matching.
+     */
     capability: string;
+    /**
+     * Fixed capability category. For category-token requires, Core matches this
+     * with `interface`; for concrete capability requires it is metadata only.
+     */
+    kind?: CapabilityKind;
+    /**
+     * Wire protocol/format implemented by this provider, e.g.
+     * "openai-compatible" or "searxng-json". This prevents provider-brand
+     * strings from becoming protocol semantics.
+     */
+    interface?: CapabilityInterface;
+    /**
+     * Optional LLM proxy provider hint (for example "ollama",
+     * "vllm", "sglang"). Only explicit values or known legacy capability names
+     * may produce this; provider-local `id` must not be promoted to providerKind.
+     */
+    providerKind?: string;
     /** Task that exposes this capability — required for resolveProvideEndpoint
      *  (§5.5) to pick the right port when an app has multiple service tasks. */
     task?: string;
     /** Optional port-name disambiguator when multiple ports share a number. */
     portName?: string;
+    /**
+     * AppSpec-declared template port. Used only to identify the task port at
+     * install/spec-validation time. It is never a runtime hostPort fact source.
+     */
     port?: number;
+    /**
+     * Upstream path exposed for this capability. Kept top-level by design;
+     * endpoint currently carries only `portName` so there is one place for path
+     * semantics and no split endpoint/top-level protocol model.
+     */
     path?: string;
+    /**
+     * Structured endpoint contract. Currently only `portName` is allowed:
+     * it selects the named runtime.ports[] entry for this concrete instance.
+     * The actual hostPort always comes from runtime.ports[].hostPort and must
+     * never be copied or inferred from AppSpec declared ports.
+     */
+    endpoint?: {
+        portName?: string;
+    };
     url?: string;
-    protocol?: "http" | "https" | "tcp" | "udp" | "ws" | "wss" | "sse" | "mcp" | "terminal" | (string & {});
+    /**
+     * Transport used by proxy/health/capability consumers. This remains a
+     * top-level provide field; do not add endpoint.protocol unless the whole
+     * schema is migrated intentionally.
+     */
+    protocol?: "http" | "https" | "tcp" | "udp" | "ws" | "wss" | "sse" | "terminal" | (string & {});
     visibility?: string;
     description?: string;
     terminal?: AppTerminalConfig;
@@ -268,7 +355,7 @@ export interface AppProvide {
      * jishushell MCP firewall uses these fields verbatim — upstream
      * `tools/list` descriptions are discarded — to prevent third-party
      * packages from prompt-injecting the LLM via their own tool wording.
-     * When absent, adapters fall back to the legacy per-capability path
+     * When absent, integrations fall back to the legacy per-capability path
      * (PR 7 in-tree shim or direct `npx <pkg>` wiring).
      */
     tool_schema?: ToolSchema;
@@ -361,7 +448,19 @@ export interface ToolSchema {
     wrap_outputs?: boolean;
 }
 export interface AppRequire {
+    /**
+     * Required capability selector. Category tokens (`llm`, `search`, ...)
+     * opt into kind/interface contract matching. Concrete names
+     * (`llm-ollama`, `search-searxng`) are exact-match requirements, even if
+     * kind/interface metadata is present for display.
+     */
     capability: string;
+    /** Consumer-local display slot; `inject_as` remains the env/config key for current integrations. */
+    slot?: string;
+    /** Structured capability category. Category-token requires match by kind + interface; concrete capability names stay exact. */
+    kind?: CapabilityKind;
+    /** Wire contract required by this consumer, e.g. "openai-compatible"; metadata only for exact capability requires. */
+    interface?: CapabilityInterface;
     inject_as: string;
     required?: boolean;
     /**
@@ -376,14 +475,16 @@ export interface AppRequire {
      * `x-jishushell.proxy.upstream` (OpenClaw / Hermes default); `"openai-env"`
      * injects `OPENAI_API_BASE_URL` / `OPENAI_API_KEY` directly into runtime
      * env (Open WebUI / generic OpenAI clients). Omit to fall back to the
-     * adapter-type default.
+     * integration-type default.
      */
     apply?: "proxy-upstream" | "openai-env";
 }
 /**
  * Persisted binding state. Stored under `instance.json.connections[slot]`.
- * `null` denotes user-explicit disconnect (do not auto-fall-back).
- * Missing slot = "never set" (legacy single-candidate fallback may apply).
+ * `null` denotes user-explicit disconnect.
+ * Missing slot = "never set". Runtime/start/status/proxy/capability paths must
+ * treat it as unbound; the only automatic provider selection is the
+ * create/install one-shot materialization that writes this canonical field.
  */
 export interface InstanceConnectionSingle {
     kind: "single";
@@ -456,8 +557,59 @@ export interface AppLifecycle {
     /** Steps run after the Nomad job transitions to `running`. */
     post_start?: AppLifecycleStep[];
 }
+/**
+ * Reference from a declarative AppSpec/AppInstance to a Core-owned native
+ * integration module.
+ *
+ * AppSpec describes how an app is installed, started, exposed, and wired to
+ * other apps. Most apps stop there.
+ *
+ * `integrations` is only for the cases where Core must also understand the
+ * app's private/native behavior: read or write its native config format,
+ * proxy a native chat API, manage plugins/models/documents, rewrite native
+ * connection files, or run app-specific backup/restore hooks.
+ *
+ * The value is a stable dispatch key (`kind`), not executable code. Core
+ * resolves it to an in-tree TypeScript module at runtime.
+ */
+export interface AppIntegrationRef {
+    /**
+     * Core-native integration dispatch key.
+     *
+     * Business meaning: "does Core need app-specific integration logic for this
+     * installed copy?" This is not the app definition id, not the instance id,
+     * and not clone lineage. Normal runtime/config/proxy code must dispatch
+     * app-private behavior from this field instead of guessing from app names or
+     * legacy `agentType`/`app_type` fields.
+     */
+    kind: string;
+}
+/**
+ * Declarative application definition.
+ *
+ * AppSpec is the common contract for every managed app in JishuShell:
+ * tasks, storage, lifecycle hooks, provides/requires, ports, and health.
+ * It is a template/recipe, not a runtime object and not a frontend enum.
+ *
+ * Install/create flows turn an AppSpec into:
+ * - `definition.yaml` / `resolved-spec.yaml` snapshots
+ * - `manifest.json` install metadata
+ * - `instance.json` runtime state (`AppInstance`)
+ *
+ * Apps that need Core-native business logic can additionally declare
+ * `integrations`, which point at Core-owned `AppIntegration` modules.
+ */
 export interface AppSpec {
     id: string;
+    apiVersion?: string;
+    /**
+     * Legacy AppSpec token source for old `${app_id}` / `${app.id}` templates.
+     *
+     * New AppSpecs should use `${instance.id}` directly in string fields. When
+     * this legacy field appears in imported/old specs, materializers may consume
+     * it only for path/string substitution. It is NOT instance identity and must
+     * never drive lifecycle, status, proxy, or port allocation.
+     */
     app_id?: string;
     name?: string;
     version?: string;
@@ -470,38 +622,188 @@ export interface AppSpec {
     singleInstance?: boolean;
     /** Custom prefix inserted before the numeric suffix for multi-instance naming. e.g. "inst" → ollama-inst1, ollama-inst2 */
     instancePrefix?: string;
+    integrations?: AppIntegrationRef[];
+    storage?: Record<string, AppStorageSpec>;
+    network?: AppNetworkSpec;
     tasks: AppTask[];
     depends_on?: Record<string, AppDependsOnEntry>;
     provides?: AppProvide[];
     requires?: AppRequire[];
     /**
-     * Target runtime for instances created from this spec. Drives the
-     * `adapter.createInstance()` dispatch in `routes/apps.ts`. When omitted,
-     * the app install flow defaults to `"openclaw"` for backward
-     * compatibility with specs authored before the multi-runtime contract
-     * (§32.2).
-     */
-    agentType?: string;
-    /**
-     * Runtime-scoped overlays the adapter applies during `createInstance()`.
-     * Plan §17 shape: `{ agentType?, defaults?, capabilities?, ... }`.
-     * Adapters are free to read extra keys (e.g. OpenClaw reads `skills` here).
+     * Integration-scoped native overlays consumed by Core-owned integration
+     * modules. Keep these keys declarative: AppSpec remains configuration,
+     * while the corresponding AppIntegration supplies executable behavior.
      */
     runtime?: Record<string, any>;
     lifecycle?: AppLifecycle;
-    /** OpenClaw runtime overlay; prefer `runtime` for new specs. */
-    openclaw?: Record<string, any>;
     _engine?: Record<string, any>;
 }
-export interface AppManifestArtifact {
+export type AppDefinition = AppSpec;
+export type ResolvedAppSpec = AppSpec;
+export interface AppDefinitionRef {
+    /**
+     * Template/builtin app identity.
+     *
+     * Business meaning: "what kind of app was used to create this instance?"
+     * This is not a concrete installed instance id. Multiple instances may share
+     * the same definition id.
+     */
+    id: string;
+    version: string;
+    digest: string;
+    source?: string;
+}
+export interface AppInstanceOperation {
+    id: string;
+    type: "install" | "start" | "stop" | "restart" | "upgrade" | "repair" | "uninstall";
+    /**
+     * Phase of the current one-shot lifecycle operation.
+     *
+     * This is control-plane progress only. It answers "what step is Core
+     * currently driving?" and must never be used as the instance's long-lived
+     * runtime state.
+     */
+    phase: string;
+    startedAt: string;
+    updatedAt: string;
+}
+export interface AppInstanceNeedsAttention {
+    code: string;
+    reason: string;
+    since: string;
+    command?: string;
+}
+export interface AppInstanceLastError {
+    operationId?: string;
+    phase?: string;
+    message: string;
+    at: string;
+}
+export interface AppInstanceStatus {
+    /**
+       * Core's most recently observed runtime state.
+       *
+       * Unlike `desiredState`, this is not user intent and not an optimistic
+       * submit result. It changes only after Core re-reads Nomad/runtime health
+       * and decides what is actually true now.
+       *
+       * `needs-migration` is a `failed` reason, not a phase:
+       * `{ phase: "failed", reason: "needs-migration" }`.
+       */
+    phase: "stopped" | "starting" | "ready" | "failed" | "unknown";
+    reason: string;
+    message?: string;
+    lastObservedAt: string;
+}
+export interface AppInstancePaths {
+    /** Canonical directory containing the instance ledger and mutable state. */
+    instanceDir: string;
+    /** Integration-owned home/config root for integrations such as OpenClaw or Hermes. */
+    integrationHome: string;
+    primaryConfig?: string;
+    secretEnv?: string;
+}
+export interface AppInstance {
+    /**
+     * Concrete installed instance identity.
+     *
+     * Business meaning: "which installed copy is this?" This is the id used by
+     * lifecycle, runtime ports, status, proxy, connections, backup, and delete.
+     * Do not substitute `definition.id`, `derivedFromInstanceId`, or integration
+     * kind for this value.
+     */
+    id: string;
+    /**
+     * Canonical concrete instance identifier.
+     *
+     * Duplicates `id` so downstream readers that work with structured metadata
+     * do not need to infer meaning from a generic field name.
+     */
+    instanceId: string;
+    name?: string;
+    description?: string;
+    /**
+     * Canonical definition/template identifier used to create this instance.
+     *
+     * This is the stable template id, not a clone source and not a legacy
+     * identity mirror.
+     */
+    definitionId: string;
+    /**
+     * Optional clone/source relationship.
+     *
+     * Only set when this instance was intentionally derived from another
+     * instance. It is not a dispatch key and must not be used as the instance's
+     * primary identity.
+     */
+    derivedFromInstanceId?: string;
+    definition: AppDefinitionRef;
+    /**
+     * Native integration modules attached to this concrete instance.
+     *
+     * Persisted in `instance.json` so runtime, config, backup, chat, and other
+     * Core services can dispatch directly without reverse-engineering identity
+     * from spec ids, app names, or frontend enums.
+     */
+    integrations?: AppIntegrationRef[];
+    /**
+     * Long-lived desired lifecycle intent set by the user/Core.
+     *
+     * `running` means "Core should keep trying to have this instance up".
+     * `stopped` means "Core should keep it down".
+     *
+     * This field does not say whether the instance is currently healthy.
+     * Observed truth lives in `status`.
+     */
+    desiredState: "stopped" | "running";
+    status: AppInstanceStatus;
+    connections: InstanceConnections;
+    operation?: AppInstanceOperation;
+    needsAttention?: AppInstanceNeedsAttention;
+    lastError?: AppInstanceLastError;
+    createdAt: string;
+    updatedAt: string;
+    runtime: Record<string, any>;
+    /** Canonical integration filesystem locations. Do not add per-integration path aliases. */
+    paths?: AppInstancePaths;
+    /** Integration/proxy metadata shared with native config editors. */
+    "x-jishushell"?: Record<string, any>;
+    /** Rebuildable runtime environment materialized from `connections`. */
+    "connections-env"?: Record<string, string>;
+    /** User-owned automatic backup policy. */
+    auto_backup?: Record<string, any>;
+    schemaVersion: number;
+    migrationsApplied: string[];
+}
+export interface AppInstallArtifact {
     type: "image" | "binary" | "dir";
     path: string;
 }
+export interface AppManifestResource {
+    kind: "image" | "binary" | "managed-file";
+    ref: string;
+    digest?: string;
+}
 export interface AppManifest {
-    id: string;
-    installed_at: string;
+    schemaVersion: 1;
+    instanceId: string;
+    definitionId: string;
+    definitionVersion: string;
+    definitionDigest: string;
+    resolvedSpecDigest: string;
+    installedAt: string;
+    updatedAt: string;
+    /**
+     * Dependencies the instance needs at runtime/install time.
+     *
+     * Presence here does not mean Core owns the resource or may delete it on
+     * rollback. Use `ownedResources` for rollback/delete-safe cleanup.
+     */
+    resources: AppManifestResource[];
+    /**
+     * Resources created by this specific install attempt / instance ownership
+     * model and therefore safe for rollback/delete cleanup.
+     */
+    ownedResources: AppManifestResource[];
     source?: string;
-    spec_hash?: string;
-    install_mode?: "app-dir" | "instance-dir";
-    artifacts?: AppManifestArtifact[];
 }

package/dist/utils/instance-lock.d.ts

@@ -9,8 +9,8 @@
  * The map self-cleans entries when the chain settles to keep memory flat.
  *
  * Use this for any code path that performs more than one file write on a
- * given instance id (PUT /connections transactor, startApp, stopApp,
- * restartApp). Operations on different instance ids never block each other.
+ * given instance id (PUT /connections transactor, startInstance, stopInstance,
+ * restartInstance). Operations on different instance ids never block each other.
  */
 /**
  * Run `fn` exclusively against `instanceId`. Returns `fn`'s value (or

package/dist/utils/instance-lock.js

@@ -9,8 +9,8 @@
  * The map self-cleans entries when the chain settles to keep memory flat.
  *
  * Use this for any code path that performs more than one file write on a
- * given instance id (PUT /connections transactor, startApp, stopApp,
- * restartApp). Operations on different instance ids never block each other.
+ * given instance id (PUT /connections transactor, startInstance, stopInstance,
+ * restartInstance). Operations on different instance ids never block each other.
  */
 const _instanceLocks = new Map();
 /**

package/dist/utils/path-safety.js

@@ -1,7 +1,7 @@
 /**
  * Path safety utilities for the Files module (W1).
  *
- * Three layers of defense (per .omc/plans/files-w1.md § 7.1):
+ * Three layers of defense:
  *   1. validateRelativePath — string-level checks (this module, no IO)
  *   2. resolveSafe          — path.resolve + prefix check (this module, no IO)
  *   3. realpath/symlink     — performed by FilesManager (defense 3, IO)

package/dist/utils/service-user.d.ts

@@ -0,0 +1,13 @@
+export interface ServiceUser {
+    username: string;
+    uid: number;
+    gid: number;
+    home?: string;
+    shell?: string;
+}
+export declare function resolveServiceUser(options?: {
+    jishuHome?: string;
+}): ServiceUser | null;
+export declare function requireServiceUser(options?: {
+    jishuHome?: string;
+}): ServiceUser;