@almadar/shell-node 1.0.0 → 1.2.0

package/LICENSE

@@ -0,0 +1,72 @@
+Business Source License 1.1
+
+Parameters
+
+Licensor:             Almadar FZE
+Licensed Work:        KFlow Builder / Almadar
+                      The Licensed Work is (c) 2025-2026 Almadar FZE.
+Additional Use Grant: You may make production use of the Licensed Work for
+                      non-commercial purposes and for internal evaluation.
+                      Production use for commercial purposes requires a
+                      commercial license from the Licensor.
+Change Date:          2030-02-01
+Change License:       Apache License, Version 2.0
+
+Terms
+
+The Licensor hereby grants you the right to copy, modify, create derivative
+works, redistribute, and make non-production use of the Licensed Work. The
+Licensor may make an Additional Use Grant, above, permitting limited
+production use.
+
+Effective on the Change Date, or the fourth anniversary of the first publicly
+available distribution of a specific version of the Licensed Work under this
+License, whichever comes first, the Licensor hereby grants you rights under
+the terms of the Change License, and the rights granted in the paragraph
+above terminate.
+
+If your use of the Licensed Work does not comply with the requirements
+currently in effect as described in this License, you must purchase a
+commercial license from the Licensor, its affiliated entities, or authorized
+resellers, or you must refrain from using the Licensed Work.
+
+All copies of the original and modified Licensed Work, and derivative works
+of the Licensed Work, are subject to this License. This License applies
+separately for each version of the Licensed Work and the Change Date may vary
+for each version of the Licensed Work released by Licensor.
+
+You must conspicuously display this License on each original or modified copy
+of the Licensed Work. If you receive the Licensed Work in original or
+modified form from a third party, the terms and conditions set forth in this
+License apply to your use of that work.
+
+Any use of the Licensed Work in violation of this License will automatically
+terminate your rights under this License for the current and all other
+versions of the Licensed Work.
+
+This License does not grant you any right in any trademark or logo of
+Licensor or its affiliates (provided that you may use a trademark or logo of
+Licensor as expressly required by this License).
+
+TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON
+AN "AS IS" BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS,
+EXPRESS OR IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND
+TITLE.
+
+---
+
+License text copyright (c) 2017 MariaDB Corporation Ab, All Rights Reserved.
+"Business Source License" is a trademark of MariaDB Corporation Ab.
+
+ADDITIONAL TERMS:
+
+Documentation (builder/packages/website/docs/) is licensed under CC BY 4.0.
+
+TRADEMARKS:
+
+"Orbital", "KFlow", "Almadar", and the Almadar logo are trademarks of
+Almadar FZE. You may not use these trademarks without prior written
+permission from Almadar FZE.
+
+For licensing inquiries: licensing@almadar.io

package/dist/OrbitalServerRuntime.d.ts

@@ -120,8 +120,7 @@ interface OrbitalServerRuntimeConfig {
      */
     secretPorts?: SecretPortsOptions;
     /**
-     * Builds the `os` host of the kernel engine from the grant port backed by the kernel (`createNodeOsHost` from
-     * `@almadar/shell-node`). Absent, every `os` ask is denied, as the native host does with none.
+     * Builds the `os` host of the kernel engine from the grant port backed by the kernel. Absent, the native add-on's `OsHost` answers (`orbital-core`'s `os_host`, in Rust); a wasm kernel has none and answers every `os` ask `unsupported`.
      */
     osHost?: (grants: OsGrantPort) => OsHostPort;
     /** The clock the kernel's `clock` ask is answered from, in epoch milliseconds; absent, the system clock. */
@@ -354,6 +353,8 @@ declare class OrbitalServerRuntime {
     setHostDispatchSink(sink: (item: HostDispatchItem) => void): void;
     /** Run a follow-on step's call outcome as its own dispatch, and hand its result to the host-dispatch sink. */
     private runDeferredOutcome;
+    /** A deferred outcome for the tab that asked is what that browser is told of it: the kernel's client view and completion payload (EXEC-DIST-8, EXEC-QUEUE-10). */
+    private browserDispatchItem;
     /**
      * A tick-stamped dispatch is a latest-state broadcast (T6): the kernel coalesces it with the others of the window
      * (newest per origin client, orbital and event) and says how long the window stays open; this host only runs
@@ -426,7 +427,7 @@ declare class OrbitalServerRuntime {
      * runs as the session's identity, never a viewer the request names. An unknown orbital is `ORBITAL_NOT_FOUND`, an undeclared
      * locale `LOCALE_NOT_DECLARED`; an inbound-only event and an undeclared input are the routes' refusals.
      */
-    dispatchEventRequest(orbital: string, parsed: EventRequest, input: boolean, stream?: boolean): Promise<DispatchRequestOutcome>;
+    dispatchEventRequest(orbital: string, parsed: EventRequest, input: boolean, stream?: boolean, wire?: boolean): Promise<DispatchRequestOutcome>;
     dispatchExternalInput(orbitalName: string, request: ExternalInputRequest, onPush?: (item: PushItem) => void): Promise<EventResponse>;
     /**
      * An inbound delivery (`/api/hooks/<name>`): the runtime decides whether the name is served, runs

package/dist/OrbitalServerRuntime.js

@@ -1,3 +1,3 @@
-export { OrbitalServerRuntime, UnresolvedProgramError } from './chunk-3PNZYEZQ.js';
-import './chunk-VQVAHUAX.js';
+export { OrbitalServerRuntime, UnresolvedProgramError } from './chunk-U2YFXKUN.js';
+import './chunk-YEC2UPB4.js';
 import './chunk-EEYGL7AB.js';

package/dist/{chunk-7QG7JGKQ.js → chunk-CB2RKJKB.js}

@@ -1,4 +1,4 @@
-import { workspacesRoot, kernelWorkspaceHost, workspaceBucketFromEnv } from './chunk-YLFK5OJN.js';
+import { workspacesRoot, kernelWorkspaceHost, workspaceBucketFromEnv } from './chunk-WIL5CHP5.js';
 import { runProgramEffect } from './chunk-7QE32QQR.js';
 import { installedWorkspaceHost, installWorkspaceHost } from './chunk-BWMLDDCL.js';
 

package/dist/{chunk-3PNZYEZQ.js → chunk-U2YFXKUN.js}

@@ -1,4 +1,4 @@
-import { installNodeHostPorts, createNodeTokenPost } from './chunk-VQVAHUAX.js';
+import { installNodeHostPorts, createNodeTokenPost, nativeOsHost } from './chunk-YEC2UPB4.js';
 import { nativeMemoryOf } from './chunk-EEYGL7AB.js';
 import { EventBus, bindDeclaredCollections, createSecretPorts, defaultCallService, kernelEventRequestParser, kernelOsTls, kernelOsCompletions, stampEmitSource, eventRouteKey, kernelOsGrants, KernelEngine, dispatchDeclaredInput, dispatchInbound, createSecretStore, evaluateOnKernel, InFlightCalls } from '@almadar/shell-runtime';
 import { installKernelEvaluator, orbitalInlineEntities, asEventId, asTraitId, inlineTraitRefs, tickEventKey, toPayloadValue } from '@almadar/core';
@@ -262,6 +262,7 @@ var OrbitalServerRuntime = class {
       deferCallOutcome: () => this.hostDispatchSink === null ? void 0 : (call) => this.runDeferredOutcome(call.orbital, {
         event: call.event,
         ...call.payload !== void 0 ? { payload: call.payload } : {},
+        ...call.heldPayload !== void 0 ? { heldPayload: call.heldPayload } : {},
         targetTrait: call.traitName,
         ...call.entityId !== void 0 ? { entityId: call.entityId } : {},
         ...call.originClientId !== void 0 ? { clientId: call.originClientId } : {},
@@ -313,7 +314,7 @@ var OrbitalServerRuntime = class {
     this.inFlightCalls.cancelAll();
     this.kernelEngine?.dispose();
     this.kernelOs?.close();
-    this.kernelOs = this.config.osHost?.(kernelOsGrants(kernel, () => this.requireKernelEngine()));
+    this.kernelOs = this.config.osHost?.(kernelOsGrants(kernel, () => this.requireKernelEngine())) ?? nativeOsHost(kernel, () => this.requireKernelEngine().serverHandle());
     this.kernelEngine = KernelEngine.open(kernel, schema, this.kernelPorts(), this.lazyDir);
     this.kernelEngine.setStateful();
     this.programSurface = this.kernelEngine.programSurface();
@@ -495,10 +496,18 @@ var OrbitalServerRuntime = class {
   /** Run a follow-on step's call outcome as its own dispatch, and hand its result to the host-dispatch sink. */
   runDeferredOutcome(orbitalName, request) {
     void this.processOrbitalEvent(orbitalName, request).then(
-      (response) => this.hostDispatchSink?.({ orbitalName, request, response, ...request.clientId !== void 0 ? { originClientId: request.clientId } : {} }),
+      (response) => this.hostDispatchSink?.(this.browserDispatchItem(orbitalName, request, response)),
       (error) => effectLog.error("deferred-outcome:failed", { orbitalName, event: request.event, trait: request.targetTrait, error: error.message })
     );
   }
+  /** A deferred outcome for the tab that asked is what that browser is told of it: the kernel's client view and completion payload (EXEC-DIST-8, EXEC-QUEUE-10). */
+  browserDispatchItem(orbitalName, request, response) {
+    if (request.clientId === void 0) return { orbitalName, request, response };
+    const engine = this.requireKernelEngine();
+    const payload = request.targetTrait === void 0 ? request.payload : engine.browserCompletionPayload(request.targetTrait, request.payload);
+    const { payload: _held, ...rest } = request;
+    return { orbitalName, request: payload === void 0 ? rest : { ...rest, payload }, response: engine.clientView(response), originClientId: request.clientId };
+  }
   /**
    * A tick-stamped dispatch is a latest-state broadcast (T6): the kernel coalesces it with the others of the window
    * (newest per origin client, orbital and event) and says how long the window stays open; this host only runs
@@ -631,9 +640,9 @@ var OrbitalServerRuntime = class {
         return this.requireKernelEngine().readRows(entity, await this.persistence.list(entity), user);
       },
       supportsDispatchStream: true,
-      dispatchRequest: (orbital, request, input, stream) => {
+      dispatchRequest: (orbital, request, input, stream, wire) => {
         assertReentry?.();
-        return this.dispatchEventRequest(orbital, request, input, stream);
+        return this.dispatchEventRequest(orbital, request, input, stream, wire);
       },
       deliverInbound: (name, delivery) => this.deliverInbound(name, delivery),
       resolveRows: (reference, clientId) => this.resolveRows(reference, clientId)
@@ -644,17 +653,20 @@ var OrbitalServerRuntime = class {
    * runs as the session's identity, never a viewer the request names. An unknown orbital is `ORBITAL_NOT_FOUND`, an undeclared
    * locale `LOCALE_NOT_DECLARED`; an inbound-only event and an undeclared input are the routes' refusals.
    */
-  async dispatchEventRequest(orbital, parsed, input, stream = false) {
+  async dispatchEventRequest(orbital, parsed, input, stream = false, wire = false) {
     const request = parsed;
     const streamItems = [];
     const onPush = stream ? (item) => {
       streamItems.push({ ...item, timestamp: item.timestamp ?? Date.now() });
     } : void 0;
-    const answer = (response2) => ({
-      ok: true,
-      response: response2,
-      ...stream ? { streamItems: [...streamItems, { type: "complete", data: response2, timestamp: Date.now() }] } : {}
-    });
+    const answer = (full) => {
+      const response2 = wire ? this.requireKernelEngine().clientView(full) : full;
+      return {
+        ok: true,
+        response: response2,
+        ...stream ? { streamItems: [...streamItems, { type: "complete", data: response2, timestamp: Date.now() }] } : {}
+      };
+    };
     if (await this.resolveRegisteredOrbital(orbital) === void 0) {
       return { ok: false, error: `Orbital not found: ${orbital}`, code: "ORBITAL_NOT_FOUND", status: 404 };
     }

package/dist/chunk-WIL5CHP5.js

@@ -0,0 +1,222 @@
+import { installNodeHostPorts, createNodeTokenPost, nativeOsHost } from './chunk-YEC2UPB4.js';
+import { loadNativeKernelModule, resolveNativeAddon, loadKernelModule } from './chunk-EEYGL7AB.js';
+import { workspaceOwnerSegment } from './chunk-BWMLDDCL.js';
+import { mkdirSync, realpathSync, mkdtempSync, writeFileSync, rmSync } from 'fs';
+import { tmpdir } from 'os';
+import { resolve, dirname, join } from 'path';
+import { spawn } from 'child_process';
+import { createRequire } from 'module';
+import { createSecretPorts, NativeMemoryPersistenceAdapter, InFlightCalls, KernelEngine, dispatchInbound } from '@almadar/shell-runtime';
+import { resolveOrbBinary } from '@almadar/core/behavior-package';
+import { tickEventKey } from '@almadar/core';
+
+function resolveKernelDir(from = process.cwd()) {
+  const named = process.env.ALMADAR_KERNEL_DIR;
+  if (named !== void 0 && named !== "") return named;
+  const entry = createRequire(join(resolve(from), "resolve.js")).resolve("@almadar/kernel");
+  return dirname(dirname(entry));
+}
+function emitPayload(run, event, read) {
+  const found = run.emits.find((emit) => emit.event === event);
+  return found === void 0 ? void 0 : read(found.payload ?? {});
+}
+async function resolveProgramFile(path, cwd = dirname(resolve(path)), orb = resolveOrbBinary(cwd)) {
+  const absolute = resolve(path);
+  return new Promise((done, fail) => {
+    const child = spawn(orb, ["resolve", absolute], { cwd, stdio: ["ignore", "pipe", "pipe"] });
+    const out = [];
+    const err = [];
+    child.stdout.on("data", (chunk) => out.push(chunk));
+    child.stderr.on("data", (chunk) => err.push(chunk));
+    child.on("error", fail);
+    child.on("close", (code) => {
+      if (code !== 0) {
+        fail(new Error(`orb resolve ${absolute} exited ${code}: ${Buffer.concat(err).toString("utf8")}`));
+        return;
+      }
+      const text = Buffer.concat(out).toString("utf8");
+      done(JSON.parse(text.slice(text.indexOf("{"))));
+    });
+  });
+}
+var KernelProgram = class _KernelProgram {
+  constructor(engine, schema, secretPorts, persistence, os) {
+    this.engine = engine;
+    this.schema = schema;
+    this.secretPorts = secretPorts;
+    this.persistence = persistence;
+    this.os = os;
+  }
+  engine;
+  schema;
+  secretPorts;
+  persistence;
+  os;
+  static async open(schema, options) {
+    const languageFrom = { languageFrom: options.languageFrom };
+    const native = options.engine === "native";
+    const addon = native ? await loadNativeKernelModule(options.nativeAddon ?? resolveNativeAddon(options.languageFrom), languageFrom) : void 0;
+    const kernelDir = addon === void 0 ? options.kernelDir ?? resolveKernelDir() : "";
+    const kernel = addon ?? await loadKernelModule(kernelDir, languageFrom);
+    installNodeHostPorts();
+    let engine;
+    const requireEngine = () => {
+      if (engine === void 0) throw new Error("KernelProgram: an ask arrived before the program opened");
+      return engine;
+    };
+    const tokenPost = createNodeTokenPost({ egressAllows: (url) => requireEngine().egressAllows(url), isPublicAddress: (ip) => kernel.isPublicAddress(ip) });
+    const secretPorts = createSecretPorts({ tokenPost, ...options.secretPorts });
+    const persistence = new NativeMemoryPersistenceAdapter(new kernel.MemoryStore());
+    for (const [entityType, rows] of Object.entries(options.seed ?? {})) {
+      for (const row of rows) await persistence.writeWhere({ kind: "upsert", entityType, data: row });
+    }
+    const ports = {
+      persistence,
+      callService: async () => null,
+      programEffect: () => void 0,
+      inFlightCalls: new InFlightCalls(),
+      servicePorts: (caller, _user, message) => ({ caller, message, inputs: () => [], readableEntities: () => [], dispatchInput: async () => {
+        throw new Error("KernelProgram has no input channel");
+      }, read: async () => [] }),
+      deliverLive: () => void 0,
+      deferCallOutcome: () => void 0,
+      secretPorts
+    };
+    const os = nativeOsHost(kernel, () => requireEngine().serverHandle());
+    if (os !== void 0) ports.os = os;
+    engine = KernelEngine.open(kernel, schema, ports);
+    return new _KernelProgram(engine, schema, secretPorts, persistence, os);
+  }
+  /** Fire `event` at the orbital as `user` (the program's `@user`), wait for its whole cascade (every secret ask included), and return what it emitted. */
+  async dispatch(orbital, event, payload = {}, targetTrait, user) {
+    const response = await this.engine.evaluate(
+      orbital,
+      { event, payload, ...targetTrait !== void 0 ? { targetTrait } : {}, ...user !== void 0 ? { user } : {} },
+      { orbital }
+    );
+    return {
+      success: response.success,
+      emits: response.emittedEvents,
+      rejections: response.rejections ?? [],
+      ...response.error !== void 0 ? { error: response.error } : {}
+    };
+  }
+  /** Fire `trait`'s tick `name` once, as a host timer would; the kernel evaluates the tick's guard and effects. */
+  async tick(orbital, trait, name) {
+    const response = await this.engine.evaluate(orbital, { event: tickEventKey(name), runTick: { trait, tick: name }, targetTrait: trait }, { orbital });
+    return {
+      success: response.success,
+      emits: response.emittedEvents,
+      rejections: response.rejections ?? [],
+      ...response.error !== void 0 ? { error: response.error } : {}
+    };
+  }
+  /** Deliver an `/api/hooks/<name>` request to the program and return the answer it gave (EXEC-INBOUND-1). */
+  async deliverInbound(name, delivery) {
+    return dispatchInbound(this.engine, name, delivery, (orbital, request) => this.engine.evaluate(orbital, request, { orbital }), (credential) => this.secretPorts.secrets.get(credential, void 0));
+  }
+  /** The rows the host's in-memory store holds for `entity` (empty when the native kernel keeps its own `store`). */
+  async rows(entity) {
+    return this.persistence.list(entity);
+  }
+  close() {
+    this.os?.close();
+    this.engine.dispose();
+  }
+};
+
+// src/program/kernel-workspace-host.ts
+var GCS_ENDPOINT = "https://storage.googleapis.com";
+var WORKSPACE_HMAC_KEY_ID = "ALMADAR_WORKSPACE_HMAC_KEY_ID";
+var WORKSPACE_HMAC_SECRET = "ALMADAR_WORKSPACE_HMAC_SECRET";
+function workspaceBucketFromEnv(env) {
+  const name = env.ALMADAR_WORKSPACE_BUCKET;
+  if (name === void 0 || name === "") return void 0;
+  return { name, endpoint: GCS_ENDPOINT, region: "auto", accessKeyId: WORKSPACE_HMAC_KEY_ID, secretAccessKey: WORKSPACE_HMAC_SECRET };
+}
+var ORBITAL = "Workspaces";
+var TRAIT = `${ORBITAL}WorkspaceClient`;
+function workspacesRoot(projectRoot) {
+  return join(projectRoot, "workspaces");
+}
+function programText(root, bucket) {
+  const egress = bucket === void 0 ? "" : `
+  egress: [${JSON.stringify(bucket.endpoint)}],`;
+  return `app kernel-workspace-host [
+  version: "1.0.0",
+  description: "The program host's workspaces, run by std-workspace.",${egress}
+  fs: { ${JSON.stringify(`${root}/**`)}: [read, write, create, remove] },
+  exec: ["git"]
+]
+uses Ws from "std/behaviors/std-workspace"
+orbital ${ORBITAL} = Ws.orbitals.WorkspaceOrbital {${bucket === void 0 ? `
+  traits { WorkspaceClient { config { root: ${JSON.stringify(root)} } } }` : `
+  traits {
+    WorkspaceClient { config { root: ${JSON.stringify(root)}, store: bucket, bucket: ${JSON.stringify(bucket.name)} } }
+    WorkspaceStore { config { endpoint: ${JSON.stringify(bucket.endpoint)}, region: ${JSON.stringify(bucket.region)}, bucket: ${JSON.stringify(bucket.name)}, accessKeyId: ${JSON.stringify(bucket.accessKeyId)}, secretAccessKey: ${JSON.stringify(bucket.secretAccessKey)} } }
+  }`}
+}
+`;
+}
+function failure(run, failed, what) {
+  const detail = emitPayload(run, failed, (p) => typeof p.message === "string" ? p.message : "");
+  return new Error(`workspace ${what} failed: ${detail ?? run.error ?? "no answer"}`);
+}
+function snapshots(payload) {
+  const rows = payload.snapshots;
+  if (!Array.isArray(rows)) return [];
+  return rows.flatMap(
+    (row) => typeof row === "object" && row !== null && !Array.isArray(row) && typeof row.id === "string" && typeof row.timestamp === "number" && typeof row.reason === "string" ? [{ id: row.id, timestamp: row.timestamp, reason: row.reason }] : []
+  );
+}
+function kernelWorkspaceHost(options) {
+  const root = workspacesRoot(options.projectRoot);
+  let program;
+  let tail = Promise.resolve();
+  const open = () => {
+    program ??= (async () => {
+      mkdirSync(root, { recursive: true });
+      const granted = realpathSync(root);
+      const dir = mkdtempSync(join(tmpdir(), "almadar-workspace-host-"));
+      try {
+        const file = join(dir, "workspace-host.lolo");
+        writeFileSync(file, programText(granted, options.bucket));
+        const schema = await resolveProgramFile(file, options.projectRoot, options.orb);
+        return await KernelProgram.open(schema, { ...options.kernel, languageFrom: options.projectRoot });
+      } finally {
+        rmSync(dir, { recursive: true, force: true });
+      }
+    })();
+    return program;
+  };
+  const run = (principal, event, payload, read) => {
+    const next = tail.then(async () => read(await (await open()).dispatch(ORBITAL, event, payload, TRAIT, { id: principal })));
+    tail = next.catch(() => void 0);
+    return next;
+  };
+  return {
+    root,
+    async open(workspace, context) {
+      const principal = context.principal;
+      if (principal === void 0 || principal === "") throw new Error("A workspace needs a signed-in caller");
+      return {
+        workDir: join(root, workspaceOwnerSegment(principal), workspaceOwnerSegment(workspace)),
+        writeFile: (path, content) => run(principal, "WORKSPACE_WRITE_FILE", { workspace, path, content }, (r) => {
+          if (emitPayload(r, "WORKSPACE_FILE_WRITTEN", (p) => p.written) !== true) throw failure(r, "WORKSPACE_WRITE_FAILED", `write of ${path}`);
+        }),
+        snapshot: (reason) => run(principal, "WORKSPACE_SNAPSHOT", { workspace, reason }, (r) => {
+          const taken = emitPayload(r, "WORKSPACE_SNAPSHOT_TAKEN", (p) => ({ committed: p.committed === true, oid: typeof p.oid === "string" ? p.oid : "" }));
+          if (taken === void 0) throw failure(r, "WORKSPACE_SNAPSHOT_FAILED", "snapshot");
+          return taken.committed ? { oid: taken.oid } : null;
+        }),
+        listSnapshots: (opts) => run(principal, "WORKSPACE_HISTORY", { workspace, ...opts?.limit !== void 0 ? { limit: opts.limit } : {} }, (r) => {
+          const found = emitPayload(r, "WORKSPACE_HISTORY_LOADED", snapshots);
+          if (found === void 0) throw failure(r, "WORKSPACE_HISTORY_FAILED", "history");
+          return found;
+        })
+      };
+    }
+  };
+}
+
+export { KernelProgram, emitPayload, kernelWorkspaceHost, resolveProgramFile, workspaceBucketFromEnv, workspacesRoot };

package/dist/{chunk-VQVAHUAX.js → chunk-YEC2UPB4.js}

@@ -2,10 +2,11 @@ import { readFile, mkdir, writeFile, rename } from 'fs/promises';
 import { join, dirname } from 'path';
 import { EntityRowSchema, runRowWrite } from '@almadar/core';
 import { AsyncLocalStorage } from 'async_hooks';
-import { installCredentialScopeStorage, CREDENTIAL_MASTER_KEY_ENV, CREDENTIAL_PREVIOUS_MASTER_KEY_ENV, CredentialVault, installCredentialStore } from '@almadar/shell-runtime';
+import { installCredentialScopeStorage, CREDENTIAL_MASTER_KEY_ENV, CREDENTIAL_PREVIOUS_MASTER_KEY_ENV, CredentialVault, installCredentialStore, createNativeOsPort } from '@almadar/shell-runtime';
 import { lookup } from 'dns/promises';
 import { request } from 'https';
 import { isIP } from 'net';
+import { homedir } from 'os';
 
 // src/credential-rows.ts
 var CREDENTIALS_FILE_ENV = "ALMADAR_CREDENTIALS_FILE";
@@ -179,5 +180,12 @@ function createNodeTokenPost(options) {
     });
   };
 }
+function nodeOsAnchors() {
+  const env = Object.fromEntries(Object.entries(process.env).flatMap(([name, value]) => value === void 0 ? [] : [[name, value]]));
+  return { home: homedir(), start: process.cwd(), exeDir: dirname(process.execPath), exe: process.execPath, env };
+}
+function nativeOsHost(kernel, server) {
+  return kernel.OsHost === void 0 ? void 0 : createNativeOsPort(kernel.OsHost, nodeOsAnchors(), server);
+}
 
-export { DEFAULT_CREDENTIALS_FILE, TokenPostRefusal, createNodeTokenPost, credentialsFilePath, fileCredentialRows, installNodeCredentialVault, installNodeHostPorts };
+export { DEFAULT_CREDENTIALS_FILE, TokenPostRefusal, createNodeTokenPost, credentialsFilePath, fileCredentialRows, installNodeCredentialVault, installNodeHostPorts, nativeOsHost };

package/dist/createProgramHandlers.js

@@ -1,6 +1,6 @@
-export { createProgramHandlers } from './chunk-7QG7JGKQ.js';
-import './chunk-YLFK5OJN.js';
-import './chunk-VQVAHUAX.js';
+export { createProgramHandlers } from './chunk-CB2RKJKB.js';
+import './chunk-WIL5CHP5.js';
+import './chunk-YEC2UPB4.js';
 import './chunk-EEYGL7AB.js';
 import './chunk-7QE32QQR.js';
 import './chunk-BWMLDDCL.js';

package/dist/index.d.ts

@@ -1,11 +1,11 @@
-import { CredentialVaultModule, CredentialVault, CredentialRowsPort, OsAnchors, OsGrantPort, OsHostPort, TokenEndpointPost, KernelModule, NativeMemoryPersistenceAdapter, ServiceCallContext, StepRequest, PlayedStep, ProgramValidationReport, ProgramEffectName, ProgramEffectOutcome } from '@almadar/shell-runtime';
+import { CredentialVaultModule, CredentialVault, CredentialRowsPort, TokenEndpointPost, KernelModule, NativeMemoryPersistenceAdapter, ServiceCallContext, StepRequest, PlayedStep, ProgramValidationReport, ProgramEffectName, ProgramEffectOutcome } from '@almadar/shell-runtime';
 import { JsonValue, KernelMemoryStoreExports, OrbitalSchema, EvaluatedProgram, ProgramValidationIssue, CatalogScope, CatalogEntry, DependencyGraph, TraitValue, TraitDescription, DescribeTarget, BehaviorDescription } from '@almadar/core';
 export { ClientEffectTuple, ClientNavigateBackTuple, ClientNavigateTuple, ClientRenderUITuple, EventRequest, EventResponse, TransitionRejection } from '@almadar/core';
 import { RequestOptions } from 'node:https';
 import { IncomingMessage, ClientRequest } from 'node:http';
 import { OsGrantsReport, ProveReport, StepRefusal } from '@almadar/core/kernel-wire';
 import { LayoutStrategy } from '@almadar/core/builders';
-export { K as KernelProgram, a as KernelProgramOptions, b as KernelWorkspaceBucket, c as KernelWorkspaceHostOptions, P as ProgramRun, W as WorkspaceHost, d as WorkspacePort, e as emitPayload, i as installWorkspaceHost, f as installedWorkspaceHost, k as kernelWorkspaceHost, r as resolveProgramFile, u as uninstallWorkspaceHost, w as workspaceBucketFromEnv, g as workspaceOwnerSegment, h as workspacesRoot } from './kernel-workspace-host-cT9JGJur.js';
+export { K as KernelProgram, a as KernelProgramOptions, b as KernelWorkspaceBucket, c as KernelWorkspaceHostOptions, P as ProgramRun, W as WorkspaceHost, d as WorkspacePort, e as emitPayload, i as installWorkspaceHost, f as installedWorkspaceHost, k as kernelWorkspaceHost, r as resolveProgramFile, u as uninstallWorkspaceHost, w as workspaceBucketFromEnv, g as workspaceOwnerSegment, h as workspacesRoot } from './kernel-workspace-host-DGAzpPX-.js';
 export { HostDispatchItem, LiveBroadcastItem, LoaderConfig, OrbitalServerRuntime, OrbitalServerRuntimeConfig, PushItem, RegisterOptions, RegisteredOrbital, RuntimeOrbital, RuntimeOrbitalSchema, UnresolvedProgramError } from './OrbitalServerRuntime.js';
 export { ProgramHandlers, ProgramHostConfig, createProgramHandlers } from './createProgramHandlers.js';
 
@@ -47,15 +47,6 @@ declare function fileCredentialRows(path: string): CredentialRowsPort;
  */
 declare function loadOrCreateDevMasterKey(dir: string): string;
 
-/** One program instance's `os` host: its own handle tables, closed by `close`. */
-interface NodeOsHostOptions {
-    /** Where `~/` and `./` and the declared grant anchors are placed; absent, the process's own (`OsAnchors::of_process`). */
-    anchors?: OsAnchors;
-}
-/** The process's home, working directory, executable directory and environment, read once (`OsAnchors::of_process`). */
-declare function processAnchors(): OsAnchors;
-declare function createNodeOsHost(grants: OsGrantPort, options?: NodeOsHostOptions): OsHostPort;
-
 type KvErrorKind = 'denied' | 'invalid' | 'io' | 'timeout' | 'unsupported' | 'closed';
 type KvResult<T> = {
     ok: true;
@@ -297,5 +288,5 @@ type EffectArg = JsonValue;
  */
 declare function runProgramEffect(op: ProgramEffectName, args: readonly EffectArg[], opts: ProgramHostOptions, context?: ProgramCallContext): Promise<ProgramEffectOutcome>;
 
-export { DEFAULT_CREDENTIALS_FILE, KvFailure, TokenPostRefusal, behaviorCatalog, behaviorCatalogSync, behaviorDependencies, behaviorDescribe, behaviorResolve, behaviorSource, createKvHost, createNodeOsHost, createNodeTokenPost, credentialsFilePath, directoryKvBackend, fileCredentialRows, installNodeCredentialVault, installNodeHostPorts, loadInstalledKernel, loadKernelModule, loadNativeKernelModule, loadOrCreateDevMasterKey, memoryKvBackend, nativeMemoryOf, processAnchors, programCompose, programEval, programOsGrants, programPrint, programProve, programRead, programResolve, programResolveSchema, programStep, programValidate, resolveNativeAddon, runProgramEffect, workspaceAccessError };
-export type { KvBackend, KvBatchOp, KvErrorKind, KvHost, KvNamespace, KvResult, LoadKernelOptions, LoadedKernel, NodeCredentialVaultOptions, NodeOsHostOptions, NodeTokenPostOptions, ProgramCallContext, ProgramComposeOptions, ProgramEvalOptions, ProgramEvalResult, ProgramHostOptions, ProgramOsGrantsReport, ProgramProveReport, ResolvedAddress };
+export { DEFAULT_CREDENTIALS_FILE, KvFailure, TokenPostRefusal, behaviorCatalog, behaviorCatalogSync, behaviorDependencies, behaviorDescribe, behaviorResolve, behaviorSource, createKvHost, createNodeTokenPost, credentialsFilePath, directoryKvBackend, fileCredentialRows, installNodeCredentialVault, installNodeHostPorts, loadInstalledKernel, loadKernelModule, loadNativeKernelModule, loadOrCreateDevMasterKey, memoryKvBackend, nativeMemoryOf, programCompose, programEval, programOsGrants, programPrint, programProve, programRead, programResolve, programResolveSchema, programStep, programValidate, resolveNativeAddon, runProgramEffect, workspaceAccessError };
+export type { KvBackend, KvBatchOp, KvErrorKind, KvHost, KvNamespace, KvResult, LoadKernelOptions, LoadedKernel, NodeCredentialVaultOptions, NodeTokenPostOptions, ProgramCallContext, ProgramComposeOptions, ProgramEvalOptions, ProgramEvalResult, ProgramHostOptions, ProgramOsGrantsReport, ProgramProveReport, ResolvedAddress };

package/dist/index.js

@@ -1,7 +1,7 @@
-export { OrbitalServerRuntime, UnresolvedProgramError } from './chunk-3PNZYEZQ.js';
-export { createProgramHandlers } from './chunk-7QG7JGKQ.js';
-export { KernelProgram, createNodeOsHost, emitPayload, kernelWorkspaceHost, processAnchors, resolveProgramFile, workspaceBucketFromEnv, workspacesRoot } from './chunk-YLFK5OJN.js';
-export { DEFAULT_CREDENTIALS_FILE, TokenPostRefusal, createNodeTokenPost, credentialsFilePath, fileCredentialRows, installNodeCredentialVault, installNodeHostPorts } from './chunk-VQVAHUAX.js';
+export { OrbitalServerRuntime, UnresolvedProgramError } from './chunk-U2YFXKUN.js';
+export { createProgramHandlers } from './chunk-CB2RKJKB.js';
+export { KernelProgram, emitPayload, kernelWorkspaceHost, resolveProgramFile, workspaceBucketFromEnv, workspacesRoot } from './chunk-WIL5CHP5.js';
+export { DEFAULT_CREDENTIALS_FILE, TokenPostRefusal, createNodeTokenPost, credentialsFilePath, fileCredentialRows, installNodeCredentialVault, installNodeHostPorts } from './chunk-YEC2UPB4.js';
 export { loadInstalledKernel, loadKernelModule, loadNativeKernelModule, nativeMemoryOf, resolveNativeAddon } from './chunk-EEYGL7AB.js';
 export { behaviorCatalog, behaviorCatalogSync, behaviorDependencies, behaviorDescribe, behaviorResolve, behaviorSource, programCompose, programEval, programOsGrants, programPrint, programProve, programRead, programResolve, programResolveSchema, programStep, programValidate, runProgramEffect, workspaceAccessError } from './chunk-7QE32QQR.js';
 export { installWorkspaceHost, installedWorkspaceHost, uninstallWorkspaceHost, workspaceOwnerSegment } from './chunk-BWMLDDCL.js';

package/dist/{kernel-workspace-host-cT9JGJur.d.ts → kernel-workspace-host-DGAzpPX-.d.ts}

@@ -56,8 +56,6 @@ interface KernelProgramOptions {
     secretPorts?: Pick<SecretPortsOptions, 'secrets' | 'random'>;
     /** Rows the program's in-memory store starts with, by entity name (a catalog the host already holds). */
     seed?: Record<string, EntityRow[]>;
-    /** Answer the program's `os` effects with the Node host (its grants are the program's own); absent, every `os` ask is denied. */
-    os?: boolean;
 }
 interface ProgramRun {
     success: boolean;
@@ -76,10 +74,10 @@ declare function emitPayload<T>(run: ProgramRun, event: string, read: (payload:
 declare function resolveProgramFile(path: string, cwd?: string, orb?: string): Promise<OrbitalSchema>;
 declare class KernelProgram {
     private readonly engine;
-    private readonly os;
     private readonly schema;
     private readonly secretPorts;
     private readonly persistence;
+    private readonly os;
     private constructor();
     static open(schema: OrbitalSchema, options: KernelProgramOptions): Promise<KernelProgram>;
     /** Fire `event` at the orbital as `user` (the program's `@user`), wait for its whole cascade (every secret ask included), and return what it emitted. */

package/dist/kernelWorkspace.d.ts

@@ -1,3 +1,3 @@
-export { b as KernelWorkspaceBucket, c as KernelWorkspaceHostOptions, k as kernelWorkspaceHost, w as workspaceBucketFromEnv, h as workspacesRoot } from './kernel-workspace-host-cT9JGJur.js';
+export { b as KernelWorkspaceBucket, c as KernelWorkspaceHostOptions, k as kernelWorkspaceHost, w as workspaceBucketFromEnv, h as workspacesRoot } from './kernel-workspace-host-DGAzpPX-.js';
 import '@almadar/shell-runtime';
 import '@almadar/core';

package/dist/kernelWorkspace.js

@@ -1,4 +1,4 @@
-export { kernelWorkspaceHost, workspaceBucketFromEnv, workspacesRoot } from './chunk-YLFK5OJN.js';
-import './chunk-VQVAHUAX.js';
+export { kernelWorkspaceHost, workspaceBucketFromEnv, workspacesRoot } from './chunk-WIL5CHP5.js';
+import './chunk-YEC2UPB4.js';
 import './chunk-EEYGL7AB.js';
 import './chunk-BWMLDDCL.js';

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@almadar/shell-node",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "orbRelease": {
     "severity": "normal"
   },
-  "description": "Almadar TS shell node runtime pack: the Node os/* and program/* host of the kernel (os families, KernelProgram, workspace, program host).",
+  "description": "Almadar TS shell node runtime pack: the Node program host of the kernel (KernelProgram, workspace, program host); os asks are answered only by the native add-on.",
   "license": "BUSL-1.1",
   "type": "module",
   "main": "./dist/index.js",
@@ -37,12 +37,12 @@
     "access": "public"
   },
   "dependencies": {
-    "@almadar/core": "^11.1.0",
-    "@almadar/kernel": "^19.0.1",
-    "@almadar/logger": "^2.1.0",
+    "@almadar/core": "^11.4.0",
+    "@almadar/kernel": "^19.2.0",
+    "@almadar/logger": "^2.4.0",
     "zod": "^4.6.7",
-    "@almadar/std": "^17.0.0",
-    "@almadar/shell-runtime": "^1.0.0"
+    "@almadar/std": "^17.2.0",
+    "@almadar/shell-runtime": "^1.2.0"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",