@node-agent/local 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 LKJacky
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,36 @@
-# Temporary Holding Version
+# @node-agent/local
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Run NodeAgentOS locally: one persistent agent, one bus, and the core nodes in a single command.
+
+## Install
+
+```bash
+npx @node-agent/local
+# open http://127.0.0.1:8790/
+```
+
+Node 23.6 or newer is required. Bring an OpenAI-compatible model key; the first run opens the
+onboarding page and stores the setup locally.
+
+## Environment
+
+| variable | meaning |
+|---|---|
+| `NODE_AGENT_BUS_PORT` | bus port; `0` picks a free one |
+| `NODE_AGENT_BUS_BIND` | bus bind address, default `127.0.0.1` |
+| `NODE_AGENT_NODES` | extra core nodes, comma separated package names |
+| `NODE_AGENT_ACCESS_TOKEN` | optional login proxy token; unset keeps the stack local |
+| `NODE_AGENT_USER` | deployment user id, default `default` |
+
+## What starts
+
+- the runtime and shared WebSocket bus
+- the persistent agent and history
+- the optional core nodes: provider, webui, notes, todo, timer, search, introduce
+
+The runtime is bundled into the launcher, so `@node-agent/runtime` does not need a separate registry
+install. Nodes stay independent packages and can be replaced or extended. See the repository README for the architecture and Node contract.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export * from 'node-agent-bus';
+export * from 'node-agent-agent';
+export * from 'node-agent-history';
+export * from './runtime/index.js';
+export * from './local.js';

package/dist/index.js

@@ -0,0 +1,9 @@
+// node-agent: the meta package — the bus (node-agent-bus) and the agent node (node-agent-agent)
+// still go out under this one name, and the backend entry serve.ts lives here too, so bin:
+// node-agent and consumers' existing imports are unchanged.
+export * from 'node-agent-bus';
+export * from 'node-agent-agent';
+export * from 'node-agent-history';
+export * from './runtime/index.js';
+export * from './local.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,gGAAgG;AAChG,2FAA2F;AAC3F,4DAA4D;AAC5D,cAAc,gBAAgB,CAAC;AAC/B,cAAc,kBAAkB,CAAC;AACjC,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,cAAc,YAAY,CAAC"}

package/dist/language-env.d.ts

@@ -0,0 +1,13 @@
+import { type Locale } from '@node-agent/sdk';
+/**
+ * The language the environment names, if it names one of ours.
+ *
+ * `LC_ALL`, `LC_MESSAGES`, `LANG`, `LANGUAGE` -- and each value in the shapes a POSIX locale comes
+ * in: `zh_CN.UTF-8`, `en_US.utf8`, `zh_CN.UTF-8@euro`. `normalizeLocale` reads all of them, because
+ * the language is the first subtag of the tag. `C`, `POSIX` and a variable that is not set name
+ * nothing of ours, so the walk moves on instead of giving up on the environment.
+ */
+export declare function languageFromEnvironment(env?: NodeJS.ProcessEnv): Locale | undefined;
+/** The locale the runtime's own ICU data resolved, asked of `Intl`: the last thing to try before
+ *  the default. A runtime built without full ICU answers `undefined` here and the walk goes on. */
+export declare function localeFromIcu(): Locale | undefined;

package/dist/language-env.js

@@ -0,0 +1,48 @@
+// The language a process runs in: the POSIX variables a locale comes from, and the locale the
+// runtime's own ICU data resolved.
+//
+// They belong to the runtime, not to every node: the runtime asks them once, at startup, to settle
+// the language a stack speaks, and stores the answer in the profile. The setup itself only reads
+// `system.language`, so no node needs a reading of `zh_CN.UTF-8` of its own -- and the SDK, which is
+// also the browser's, stays free of `process`.
+import { normalizeLocale } from '@node-agent/sdk';
+/** The POSIX variables that name a language, in the order POSIX gives them. */
+const LOCALE_VARIABLES = ['LC_ALL', 'LC_MESSAGES', 'LANG', 'LANGUAGE'];
+/** The tags one variable holds: `LANGUAGE` is a colon-separated list, the others hold one tag. */
+function tagsOf(value) {
+    if (typeof value !== 'string')
+        return [];
+    return value
+        .split(':')
+        .map((one) => one.trim())
+        .filter((one) => one !== '');
+}
+/**
+ * The language the environment names, if it names one of ours.
+ *
+ * `LC_ALL`, `LC_MESSAGES`, `LANG`, `LANGUAGE` -- and each value in the shapes a POSIX locale comes
+ * in: `zh_CN.UTF-8`, `en_US.utf8`, `zh_CN.UTF-8@euro`. `normalizeLocale` reads all of them, because
+ * the language is the first subtag of the tag. `C`, `POSIX` and a variable that is not set name
+ * nothing of ours, so the walk moves on instead of giving up on the environment.
+ */
+export function languageFromEnvironment(env = process.env) {
+    for (const name of LOCALE_VARIABLES) {
+        for (const tag of tagsOf(env[name])) {
+            const locale = normalizeLocale(tag);
+            if (locale !== null)
+                return locale;
+        }
+    }
+    return undefined;
+}
+/** The locale the runtime's own ICU data resolved, asked of `Intl`: the last thing to try before
+ *  the default. A runtime built without full ICU answers `undefined` here and the walk goes on. */
+export function localeFromIcu() {
+    try {
+        return normalizeLocale(Intl.DateTimeFormat().resolvedOptions().locale) ?? undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=language-env.js.map

package/dist/language-env.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"language-env.js","sourceRoot":"","sources":["../src/language-env.ts"],"names":[],"mappings":"AAAA,8FAA8F;AAC9F,mCAAmC;AACnC,EAAE;AACF,mGAAmG;AACnG,iGAAiG;AACjG,qGAAqG;AACrG,+CAA+C;AAC/C,OAAO,EAAE,eAAe,EAAe,MAAM,iBAAiB,CAAC;AAE/D,+EAA+E;AAC/E,MAAM,gBAAgB,GAAG,CAAC,QAAQ,EAAE,aAAa,EAAE,MAAM,EAAE,UAAU,CAAU,CAAC;AAEhF,kGAAkG;AAClG,SAAS,MAAM,CAAC,KAAyB;IACvC,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,EAAE,CAAC;IACzC,OAAO,KAAK;SACT,KAAK,CAAC,GAAG,CAAC;SACV,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC;SACxB,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,KAAK,EAAE,CAAC,CAAC;AACjC,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,uBAAuB,CAAC,GAAG,GAAsB,OAAO,CAAC,GAAG;IAC1E,KAAK,MAAM,IAAI,IAAI,gBAAgB,EAAE,CAAC;QACpC,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC;YACpC,MAAM,MAAM,GAAG,eAAe,CAAC,GAAG,CAAC,CAAC;YACpC,IAAI,MAAM,KAAK,IAAI;gBAAE,OAAO,MAAM,CAAC;QACrC,CAAC;IACH,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;mGACmG;AACnG,MAAM,UAAU,aAAa;IAC3B,IAAI,CAAC;QACH,OAAO,eAAe,CAAC,IAAI,CAAC,cAAc,EAAE,CAAC,eAAe,EAAE,CAAC,MAAM,CAAC,IAAI,SAAS,CAAC;IACtF,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC"}

package/dist/local.d.ts

@@ -0,0 +1,44 @@
+import { Bus } from 'node-agent-bus';
+import { type BusHandle, type BusOptions, type NodeHandle, type NodeOptions, type Runtime, type RuntimeServerOptions, type UserHandle } from './runtime/index.js';
+export declare class LocalRuntime implements Runtime {
+    /** One node launch at a time: two users asking at startup must not spawn the same shared node twice. */
+    private launchQueue;
+    private readonly options;
+    private readonly logger?;
+    private busRecord;
+    private readonly nodes;
+    private readonly knownUsers;
+    constructor(options?: RuntimeServerOptions);
+    /** The shared bus, once it is listening. Used by the process entry to print its user table. */
+    get bus(): Bus | undefined;
+    private home;
+    private nodeHome;
+    /** The bus never sees a display name: it sees a stable digest of the name. */
+    private busId;
+    busUser(user: string): string;
+    private tokenFor;
+    launchBus(options?: BusOptions): Promise<BusHandle>;
+    stopBus(): Promise<void>;
+    launchNode(node: string, options?: NodeOptions): Promise<NodeHandle>;
+    private launchNodeNow;
+    stopNode(node: string): Promise<void>;
+    createUser(user: string): Promise<UserHandle>;
+    destroyUser(user: string): Promise<void>;
+    connect(user: string, node: string, options?: NodeOptions): Promise<NodeHandle>;
+    disconnect(user: string, node: string): Promise<void>;
+    /** Every user this runtime has connected, and the shared nodes each one may reach. */
+    sessions(user?: string): Promise<Record<string, unknown>>;
+    /** The newest package the installer materialized for this user, if there is one. */
+    private installedPackage;
+    private nodeRunning;
+    /** Where the shared page node printed its address, if it has started yet. */
+    private webuiTarget;
+    /** The shared bus, for a trusted caller that has to proxy an outside node. */
+    busTarget(): {
+        url: string;
+        token: string;
+    } | undefined;
+    /** Recent stdout/stderr of one running node, for the entry process to surface its address. */
+    nodeOutput(node: string): string | undefined;
+    stopAll(): Promise<void>;
+}