@metta-ts/das-client 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MesTTo
+
+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

@@ -0,0 +1,72 @@
+# @metta-ts/das-client
+
+A client for SingularityNET's Distributed AtomSpace (DAS). It lets a MeTTa TS program query a remote, shared atomspace over gRPC, and it presents that DAS as a `Space` backend, so a DAS drops in wherever an in-memory space would. It is Node-only, because a participant hosts an inbound bus node; from the browser you reach a DAS through [`@metta-ts/das-gateway`](../das-gateway).
+
+## Install
+
+```bash
+npm install @metta-ts/das-client
+```
+
+## Querying a DAS
+
+A DAS query is a network round-trip, so it is asynchronous. `DasLiveSpace` is the async analogue of an in-memory space, and `matchAsync` is the async analogue of `(match space pattern template)`: it queries the space and instantiates a template under each binding.
+
+```ts
+import { DasLiveSpace, matchAsync } from "@metta-ts/das-client";
+import { sym, expr, variable } from "@metta-ts/core";
+
+const A = (...xs) => expr(xs);
+const space = new DasLiveSpace(/* connection */);
+
+const results = await matchAsync(space, A(sym("parent"), sym("Tom"), variable("c")));
+console.log(results.map(String));
+```
+
+For tests and local development, `MockTransport` exercises the same query path without a running DAS. Build a `DasSpace` over it, run your queries against canned answers, then swap in the real transport.
+
+## Running against a live DAS
+
+The client is Node-only but cross-platform (Linux, macOS, Windows). The cluster below is stood up with `das-cli` + Docker; the steps and the one gotcha are what was verified on Linux. The loader (`db_loader`) and the Query Agent come from the same das image, so their atom handles agree.
+
+```bash
+git clone https://github.com/singnet/das-toolbox.git
+pip install -e das-toolbox/das-cli   # in a fresh venv; the system das-cli may be stale
+das-cli config set                   # accept defaults: Redis :40020, MongoDB :40021, AB :40001, QA :40002
+das-cli db start                     # Redis + MongoDB
+das-cli metta load /tmp/animals.metta  # via the db_loader container; animals.metta is in hyperon-experimental/integration_tests/das
+das-cli ab start                     # Attention Broker
+das-cli qa start                     # Query Agent (serves pattern_matching_query)
+
+DAS_LIVE=1 pnpm vitest run packages/das-client/src/live-query.test.ts
+```
+
+Two things to know:
+
+- **Query leaves are bare Symbols, not quoted strings.** `animals.metta` stores `is_animal`, `human`, etc. as Symbols, so build the pattern with `sym("is_animal")`, not `gstr("is_animal")` / `sym('"is_animal"')`. (An older das quoted string literals; that is gone.)
+- **Linux only: pin MongoDB to 7.0.** On Linux kernels >= 6.19, das-cli's default `mongodb-community-server:8.x` refuses to start (`ERROR: ... tcmalloc ... known issue with the v6.19 and newer Linux kernel`). Set `MONGODB_IMAGE_NAME = "mongo"` and `MONGODB_IMAGE_VERSION = "7.0"` in das-cli's `settings/config.py` so `db start` succeeds. Other platforms (and older kernels) run the 8.x default fine.
+
+A pattern with a variable then returns the matched bindings:
+
+```
+(EVALUATION (PREDICATE is_animal) (CONCEPT $C))
+  -> chimp earthworm ent human monkey rhino snake triceratops
+```
+
+`$C` binds to the matched `CONCEPT` node handle, not the enclosing `(CONCEPT ...)` link.
+
+## How a query is run
+
+`queryPatternMatching` runs the whole exchange against a Query Agent in three steps.
+
+It encodes the pattern as a prefix token stream (`query-tokens.ts`) using the DAS opcodes `LINK_TEMPLATE`, `LINK`, `NODE`, `VARIABLE`, and `ATOM`, the same stack machine as das-mono's `PatternMatchingQueryProcessor::setup_query_tree`. A link containing a variable is a `LINK_TEMPLATE`; a fully ground one is a `LINK`.
+
+It issues the tokens as a `pattern_matching_query` with the `ServiceBus::issue_bus_command` framing, and hosts an inbound proxy node so the agent can stream answers back.
+
+It decodes the streamed `answer_bundle` messages (`answer.ts`): it unwraps the `bus_command_proxy` envelope, then parses each `QueryAnswer` string into its variable assignment and matched handles.
+
+Atom-handle hashing (`handle.ts`) is a port of `hyperon_das/hasher.py` and produces the same handles as the live AtomDB, which is what makes the handles in the query and in the decoded answers line up. The encoder and decoder have offline tests built from a captured answer, so the protocol stays covered with no DAS running.
+
+## Version matching
+
+The released `1.0.0` Query Agent serves the `dasproto.AtomSpaceNode` service. A later `das-proto` renamed it to `DistributedAlgorithmNode`, and calling the new contract against the old agent returns gRPC `UNIMPLEMENTED`. The client carries both generated contracts, and the live path uses the one the running agent serves. Regenerate the stubs with `pnpm --filter @metta-ts/das-client gen` (needs `protoc`).

package/dist/index.d.ts

@@ -0,0 +1,223 @@
+import { Atom, Bindings, Space } from '@metta-ts/core';
+import { BinaryWriter, BinaryReader } from '@bufbuild/protobuf/wire';
+
+interface DasTransport {
+    /** Pattern-matching query against the remote space; returns binding sets (DAS `query`). */
+    query(pattern: Atom): Bindings[];
+    /** Insert an atom through DAS `add_link` / atomdb write. */
+    add(atom: Atom): void;
+    remove(atom: Atom): boolean;
+    /** Enumerate atoms (where the backend supports it). */
+    atoms(): readonly Atom[];
+}
+/** In-process transport over a local atom list for tests and offline development.
+ *  Uses the same `DasSpace`/grounded-op path as a bus client, without the network. */
+declare class MockTransport implements DasTransport {
+    private readonly store;
+    constructor(store?: Atom[]);
+    query(pattern: Atom): Bindings[];
+    add(atom: Atom): void;
+    remove(atom: Atom): boolean;
+    atoms(): readonly Atom[];
+}
+
+declare class DasSpace implements Space {
+    private readonly transport;
+    constructor(transport: DasTransport);
+    add(atom: Atom): void;
+    remove(atom: Atom): boolean;
+    query(pattern: Atom): Bindings[];
+    atoms(): readonly Atom[];
+}
+
+declare function computeHash(input: string): string;
+/** Hash of a named type (`named_type_hash`). */
+declare function namedTypeHash(name: string): string;
+/** Hash of a terminal node `(type, name)` (`terminal_hash`). */
+declare function terminalHash(type: string, name: string): string;
+/** Hash of a composite of element handles (`composite_hash`). */
+declare function compositeHash(elements: readonly string[]): string;
+/** Hash of an expression: the type hash followed by the element handles (`expression_hash`). */
+declare function expressionHash(typeHash: string, elements: readonly string[]): string;
+
+interface Ack {
+    error: boolean;
+    msg: string;
+}
+declare const Ack: MessageFns$1<Ack>;
+type Builtin$1 = Date | Function | Uint8Array | string | number | boolean | undefined;
+type DeepPartial$1<T> = T extends Builtin$1 ? T : T extends globalThis.Array<infer U> ? globalThis.Array<DeepPartial$1<U>> : T extends ReadonlyArray<infer U> ? ReadonlyArray<DeepPartial$1<U>> : T extends {} ? {
+    [K in keyof T]?: DeepPartial$1<T[K]>;
+} : Partial<T>;
+type KeysOfUnion<T> = T extends T ? keyof T : never;
+type Exact<P, I extends P> = P extends Builtin$1 ? P : P & {
+    [K in keyof P]: Exact<P[K], I[K]>;
+} & {
+    [K in Exclude<keyof I, KeysOfUnion<P>>]: never;
+};
+interface MessageFns$1<T> {
+    encode(message: T, writer?: BinaryWriter): BinaryWriter;
+    decode(input: BinaryReader | Uint8Array, length?: number): T;
+    fromJSON(object: any): T;
+    toJSON(message: T): unknown;
+    create<I extends Exact<DeepPartial$1<T>, I>>(base?: I): T;
+    fromPartial<I extends Exact<DeepPartial$1<T>, I>>(object: I): T;
+}
+
+interface MessageData {
+    command: string;
+    args: string[];
+    sender: string;
+    isBroadcast: boolean;
+    visitedRecipients: string[];
+}
+declare const MessageData: MessageFns<MessageData>;
+type Builtin = Date | Function | Uint8Array | string | number | boolean | undefined;
+type DeepPartial<T> = T extends Builtin ? T : T extends globalThis.Array<infer U> ? globalThis.Array<DeepPartial<U>> : T extends ReadonlyArray<infer U> ? ReadonlyArray<DeepPartial<U>> : T extends {} ? {
+    [K in keyof T]?: DeepPartial<T[K]>;
+} : Partial<T>;
+interface MessageFns<T> {
+    encode(message: T, writer?: BinaryWriter): BinaryWriter;
+    decode(input: BinaryReader | Uint8Array, length?: number): T;
+    fromJSON(object: any): T;
+    toJSON(message: T): unknown;
+    create(base?: DeepPartial<T>): T;
+    fromPartial(object: DeepPartial<T>): T;
+}
+
+/** Bus command names from Python/Rust `service_bus` clients. */
+declare const BusCommand: {
+    readonly ping: "ping";
+    readonly ack: "ack";
+    readonly nodeJoinedNetwork: "node_joined_network";
+    readonly busCommandProxy: "bus_command_proxy";
+    readonly queryAnswerTokensFlow: "query_answer_tokens_flow";
+};
+type MessageHandler = (msg: MessageData) => void;
+/** Inbound gRPC node plus peer `execute_message` sender. */
+declare class BusNode {
+    readonly address: string;
+    private readonly onMessage;
+    private server?;
+    constructor(address: string, onMessage?: MessageHandler);
+    /** Start the inbound gRPC server. Resolves once it is listening. */
+    start(): Promise<void>;
+    /** Send a command message to a peer node and await its acknowledgement. */
+    send(peer: string, message: MessageData): Promise<void>;
+    /** Ping a peer node; resolves with its `Ack`. */
+    ping(peer: string): Promise<Ack>;
+    stop(): Promise<void>;
+}
+
+type Pattern = {
+    kind: "node";
+    type: string;
+    name: string;
+} | {
+    kind: "var";
+    name: string;
+} | {
+    kind: "atom";
+    handle: string;
+} | {
+    kind: "expr";
+    children: Pattern[];
+};
+/** A leaf symbol node, e.g. `EVALUATION` -> NODE Symbol EVALUATION. */
+declare const node: (name: string, type?: string) => Pattern;
+/** A query variable, e.g. `$C` -> VARIABLE C. */
+declare const variable: (name: string) => Pattern;
+/** An expression (link), e.g. `(CONCEPT $C)`. */
+declare const expr: (...children: Pattern[]) => Pattern;
+/** Emit the prefix token stream for a pattern (the `query` argument of a pattern_matching_query). */
+declare function encodeQuery(p: Pattern, linkType?: string): string[];
+
+declare const PROXY_COMMAND = "bus_command_proxy";
+declare const ANSWER_BUNDLE = "answer_bundle";
+declare const FINISHED = "finished";
+declare const ABORT = "abort";
+/** One query answer: variable bindings, matched link handles, and optional handle -> MeTTa text. */
+interface QueryAnswer {
+    readonly assignment: Record<string, string>;
+    readonly handles: readonly string[];
+    readonly metta: Record<string, string>;
+}
+/** Unwrap a `bus_command_proxy` message into its inner peer command and arguments. */
+declare function unwrapProxyMessage(args: readonly string[]): {
+    command: string;
+    args: string[];
+};
+/** Parse one `QueryAnswer::tokenize` string into assignment, matched handles, and optional handle -> MeTTa text.
+ *  MeTTa values may contain spaces and parentheses, so scan with a cursor instead of splitting,
+ *  matching das-mono QueryAnswer::untokenize (read_token + read_metta_expression). */
+declare function parseQueryAnswer(token: string): QueryAnswer;
+/** Fold received proxy messages into answers plus FINISHED/ABORT state.
+ *  Only `bus_command_proxy` messages carry answers. */
+declare function collectAnswers(messages: ReadonlyArray<{
+    command: string;
+    args: readonly string[];
+}>): {
+    answers: QueryAnswer[];
+    finished: boolean;
+    aborted: boolean;
+};
+
+interface QueryOptions {
+    /** Host for the inbound proxy node (default `127.0.0.1`). The port is OS-assigned per query, so
+     *  calls never collide on a port or reuse a bus node id. */
+    readonly proxyHost?: string;
+    /** Address of the live DAS Query Agent that owns `pattern_matching_query`. */
+    readonly agentAddress: string;
+    /** Query pattern; any nested variable makes it a template. */
+    readonly pattern: Pattern;
+    /** Optional query context string (defaults to empty). */
+    readonly context?: string;
+    /** Wait deadline for FINISHED/ABORT from the agent. */
+    readonly timeoutMs?: number;
+    /** Request handle -> MeTTa text mappings so bindings resolve without a separate AtomDB read. */
+    readonly populateMettaMapping?: boolean;
+}
+interface QueryResult {
+    readonly answers: QueryAnswer[];
+    readonly finished: boolean;
+    readonly aborted: boolean;
+}
+/**
+ * Issue a pattern-matching query against a live DAS Query Agent and return the decoded answers.
+ *
+ * Wire framing (das-mono ServiceBus::issue_bus_command + BaseQueryProxy::tokenize):
+ *   command = "pattern_matching_query"
+ *   args = [requestor_id, serial, requestor_proxy_node_id,
+ *           numParamTokens, ...paramTokens, context, numQueryTokens, ...queryTokens]
+ * With no param tokens, the agent uses its configured defaults.
+ *
+ * The proxy node binds an OS-assigned port (`host:0`), so its bus node id is unique to this call.
+ * Concurrent and back-to-back queries avoid port collisions and the agent's "node already in the
+ * network" guard.
+ */
+declare function queryPatternMatching(opts: QueryOptions): Promise<QueryResult>;
+
+/** A knowledge store queried asynchronously (a remote/distributed AtomSpace). */
+interface AsyncSpace {
+    /** All binding sets under which `pattern` matches a stored atom. */
+    queryAsync(pattern: Atom): Promise<Bindings[]>;
+}
+/** Convert a core MeTTa atom into a DAS query pattern. Symbols become `Symbol` nodes; string values
+ *  become quoted `Symbol` nodes because DAS stores `"foo"` as a symbol name with quotes.
+ *  Variables and expressions map recursively. Grounded error/unit/ext throw because they have no
+ *  faithful DAS encoding. */
+declare function atomToPattern(a: Atom): Pattern;
+/** Live DAS async space. Each query hosts a proxy node for streamed answers and resolves bindings
+ *  through the answer's MeTTa mapping. */
+declare class DasLiveSpace implements AsyncSpace {
+    private readonly agentAddress;
+    private readonly timeoutMs;
+    private readonly proxyHost;
+    constructor(agentAddress: string, proxyHost?: string, timeoutMs?: number);
+    queryAsync(pattern: Atom): Promise<Bindings[]>;
+}
+/** Query the space, then instantiate `template` under each binding.
+ *  Defaults to instantiating `pattern`. */
+declare function matchAsync(space: AsyncSpace, pattern: Atom, template?: Atom): Promise<Atom[]>;
+
+export { ABORT, ANSWER_BUNDLE, type AsyncSpace, BusCommand, BusNode, DasLiveSpace, DasSpace, type DasTransport, FINISHED, type MessageHandler, MockTransport, PROXY_COMMAND, type Pattern, type QueryAnswer, type QueryOptions, type QueryResult, atomToPattern, collectAnswers, compositeHash, computeHash, encodeQuery, expr, expressionHash, matchAsync, namedTypeHash, node, parseQueryAnswer, queryPatternMatching, terminalHash, unwrapProxyMessage, variable };

package/dist/index.js

@@ -0,0 +1,888 @@
+// src/transport.ts
+import { matchAtoms } from "@metta-ts/core";
+var MockTransport = class {
+  constructor(store = []) {
+    this.store = store;
+  }
+  store;
+  query(pattern) {
+    const out = [];
+    for (const a of this.store) for (const b of matchAtoms(pattern, a)) out.push(b);
+    return out;
+  }
+  add(atom) {
+    this.store.push(atom);
+  }
+  remove(atom) {
+    const i = this.store.findIndex((a) => JSON.stringify(a) === JSON.stringify(atom));
+    if (i < 0) return false;
+    this.store.splice(i, 1);
+    return true;
+  }
+  atoms() {
+    return this.store;
+  }
+};
+
+// src/das-space.ts
+import "@metta-ts/core";
+var DasSpace = class {
+  constructor(transport) {
+    this.transport = transport;
+  }
+  transport;
+  add(atom) {
+    this.transport.add(atom);
+  }
+  remove(atom) {
+    return this.transport.remove(atom);
+  }
+  query(pattern) {
+    return this.transport.query(pattern);
+  }
+  atoms() {
+    return this.transport.atoms();
+  }
+};
+
+// src/handle.ts
+import { createHash } from "crypto";
+var JOINING_CHAR = " ";
+var MAX_LITERAL_OR_SYMBOL_SIZE = 1e4;
+var MAX_HASHABLE_STRING_SIZE = 1e5;
+function computeHash(input) {
+  return createHash("md5").update(input, "utf8").digest("hex");
+}
+function namedTypeHash(name) {
+  return computeHash(name);
+}
+function terminalHash(type, name) {
+  if (type.length + name.length >= MAX_HASHABLE_STRING_SIZE)
+    throw new Error("Invalid (too large) terminal name");
+  return computeHash(`${type}${JOINING_CHAR}${name}`);
+}
+function compositeHash(elements) {
+  let total = 0;
+  for (const e of elements) {
+    if (e.length > MAX_LITERAL_OR_SYMBOL_SIZE)
+      throw new Error("Invalid (too large) composite elements");
+    total += e.length;
+  }
+  if (total >= MAX_HASHABLE_STRING_SIZE) throw new Error("Invalid (too large) composite elements");
+  return computeHash(elements.join(JOINING_CHAR));
+}
+function expressionHash(typeHash, elements) {
+  return compositeHash([typeHash, ...elements]);
+}
+
+// src/bus-node.ts
+import {
+  Server,
+  ServerCredentials,
+  credentials
+} from "@grpc/grpc-js";
+
+// src/gen/distributed_algorithm_node.ts
+import { BinaryReader as BinaryReader2, BinaryWriter as BinaryWriter2 } from "@bufbuild/protobuf/wire";
+import {
+  makeGenericClientConstructor
+} from "@grpc/grpc-js";
+
+// src/gen/common.ts
+import { BinaryReader, BinaryWriter } from "@bufbuild/protobuf/wire";
+function createBaseEmpty() {
+  return {};
+}
+var Empty = {
+  encode(_, writer = new BinaryWriter()) {
+    return writer;
+  },
+  decode(input, length) {
+    const reader = input instanceof BinaryReader ? input : new BinaryReader(input);
+    const end = length === void 0 ? reader.len : reader.pos + length;
+    const message = createBaseEmpty();
+    while (reader.pos < end) {
+      const tag = reader.uint32();
+      switch (tag >>> 3) {
+      }
+      if ((tag & 7) === 4 || tag === 0) {
+        break;
+      }
+      reader.skip(tag & 7);
+    }
+    return message;
+  },
+  fromJSON(_) {
+    return {};
+  },
+  toJSON(_) {
+    const obj = {};
+    return obj;
+  },
+  create(base) {
+    return Empty.fromPartial(base ?? {});
+  },
+  fromPartial(_) {
+    const message = createBaseEmpty();
+    return message;
+  }
+};
+function createBaseAck() {
+  return { error: false, msg: "" };
+}
+var Ack = {
+  encode(message, writer = new BinaryWriter()) {
+    if (message.error !== false) {
+      writer.uint32(8).bool(message.error);
+    }
+    if (message.msg !== "") {
+      writer.uint32(18).string(message.msg);
+    }
+    return writer;
+  },
+  decode(input, length) {
+    const reader = input instanceof BinaryReader ? input : new BinaryReader(input);
+    const end = length === void 0 ? reader.len : reader.pos + length;
+    const message = createBaseAck();
+    while (reader.pos < end) {
+      const tag = reader.uint32();
+      switch (tag >>> 3) {
+        case 1: {
+          if (tag !== 8) {
+            break;
+          }
+          message.error = reader.bool();
+          continue;
+        }
+        case 2: {
+          if (tag !== 18) {
+            break;
+          }
+          message.msg = reader.string();
+          continue;
+        }
+      }
+      if ((tag & 7) === 4 || tag === 0) {
+        break;
+      }
+      reader.skip(tag & 7);
+    }
+    return message;
+  },
+  fromJSON(object) {
+    return {
+      error: isSet(object.error) ? globalThis.Boolean(object.error) : false,
+      msg: isSet(object.msg) ? globalThis.String(object.msg) : ""
+    };
+  },
+  toJSON(message) {
+    const obj = {};
+    if (message.error !== false) {
+      obj.error = message.error;
+    }
+    if (message.msg !== "") {
+      obj.msg = message.msg;
+    }
+    return obj;
+  },
+  create(base) {
+    return Ack.fromPartial(base ?? {});
+  },
+  fromPartial(object) {
+    const message = createBaseAck();
+    message.error = object.error ?? false;
+    message.msg = object.msg ?? "";
+    return message;
+  }
+};
+function isSet(value) {
+  return value !== null && value !== void 0;
+}
+
+// src/gen/distributed_algorithm_node.ts
+function createBaseMessageData() {
+  return { command: "", args: [], sender: "", isBroadcast: false, visitedRecipients: [] };
+}
+var MessageData = {
+  encode(message, writer = new BinaryWriter2()) {
+    if (message.command !== "") {
+      writer.uint32(10).string(message.command);
+    }
+    for (const v of message.args) {
+      writer.uint32(18).string(v);
+    }
+    if (message.sender !== "") {
+      writer.uint32(26).string(message.sender);
+    }
+    if (message.isBroadcast !== false) {
+      writer.uint32(32).bool(message.isBroadcast);
+    }
+    for (const v of message.visitedRecipients) {
+      writer.uint32(42).string(v);
+    }
+    return writer;
+  },
+  decode(input, length) {
+    const reader = input instanceof BinaryReader2 ? input : new BinaryReader2(input);
+    const end = length === void 0 ? reader.len : reader.pos + length;
+    const message = createBaseMessageData();
+    while (reader.pos < end) {
+      const tag = reader.uint32();
+      switch (tag >>> 3) {
+        case 1: {
+          if (tag !== 10) {
+            break;
+          }
+          message.command = reader.string();
+          continue;
+        }
+        case 2: {
+          if (tag !== 18) {
+            break;
+          }
+          message.args.push(reader.string());
+          continue;
+        }
+        case 3: {
+          if (tag !== 26) {
+            break;
+          }
+          message.sender = reader.string();
+          continue;
+        }
+        case 4: {
+          if (tag !== 32) {
+            break;
+          }
+          message.isBroadcast = reader.bool();
+          continue;
+        }
+        case 5: {
+          if (tag !== 42) {
+            break;
+          }
+          message.visitedRecipients.push(reader.string());
+          continue;
+        }
+      }
+      if ((tag & 7) === 4 || tag === 0) {
+        break;
+      }
+      reader.skip(tag & 7);
+    }
+    return message;
+  },
+  fromJSON(object) {
+    return {
+      command: isSet2(object.command) ? globalThis.String(object.command) : "",
+      args: globalThis.Array.isArray(object?.args) ? object.args.map((e) => globalThis.String(e)) : [],
+      sender: isSet2(object.sender) ? globalThis.String(object.sender) : "",
+      isBroadcast: isSet2(object.isBroadcast) ? globalThis.Boolean(object.isBroadcast) : isSet2(object.is_broadcast) ? globalThis.Boolean(object.is_broadcast) : false,
+      visitedRecipients: globalThis.Array.isArray(object?.visitedRecipients) ? object.visitedRecipients.map((e) => globalThis.String(e)) : globalThis.Array.isArray(object?.visited_recipients) ? object.visited_recipients.map((e) => globalThis.String(e)) : []
+    };
+  },
+  toJSON(message) {
+    const obj = {};
+    if (message.command !== "") {
+      obj.command = message.command;
+    }
+    if (message.args?.length) {
+      obj.args = message.args;
+    }
+    if (message.sender !== "") {
+      obj.sender = message.sender;
+    }
+    if (message.isBroadcast !== false) {
+      obj.isBroadcast = message.isBroadcast;
+    }
+    if (message.visitedRecipients?.length) {
+      obj.visitedRecipients = message.visitedRecipients;
+    }
+    return obj;
+  },
+  create(base) {
+    return MessageData.fromPartial(base ?? {});
+  },
+  fromPartial(object) {
+    const message = createBaseMessageData();
+    message.command = object.command ?? "";
+    message.args = object.args?.map((e) => e) || [];
+    message.sender = object.sender ?? "";
+    message.isBroadcast = object.isBroadcast ?? false;
+    message.visitedRecipients = object.visitedRecipients?.map((e) => e) || [];
+    return message;
+  }
+};
+var DistributedAlgorithmNodeService = {
+  ping: {
+    path: "/dasproto.DistributedAlgorithmNode/ping",
+    requestStream: false,
+    responseStream: false,
+    requestSerialize: (value) => Buffer.from(Empty.encode(value).finish()),
+    requestDeserialize: (value) => Empty.decode(value),
+    responseSerialize: (value) => Buffer.from(Ack.encode(value).finish()),
+    responseDeserialize: (value) => Ack.decode(value)
+  },
+  executeMessage: {
+    path: "/dasproto.DistributedAlgorithmNode/execute_message",
+    requestStream: false,
+    responseStream: false,
+    requestSerialize: (value) => Buffer.from(MessageData.encode(value).finish()),
+    requestDeserialize: (value) => MessageData.decode(value),
+    responseSerialize: (value) => Buffer.from(Empty.encode(value).finish()),
+    responseDeserialize: (value) => Empty.decode(value)
+  }
+};
+var DistributedAlgorithmNodeClient = makeGenericClientConstructor(
+  DistributedAlgorithmNodeService,
+  "dasproto.DistributedAlgorithmNode"
+);
+function isSet2(value) {
+  return value !== null && value !== void 0;
+}
+
+// src/bus-node.ts
+var BusCommand = {
+  ping: "ping",
+  ack: "ack",
+  nodeJoinedNetwork: "node_joined_network",
+  busCommandProxy: "bus_command_proxy",
+  queryAnswerTokensFlow: "query_answer_tokens_flow"
+};
+var BusNode = class {
+  constructor(address, onMessage = () => {
+  }) {
+    this.address = address;
+    this.onMessage = onMessage;
+  }
+  address;
+  onMessage;
+  server;
+  /** Start the inbound gRPC server. Resolves once it is listening. */
+  start() {
+    const server = new Server();
+    server.addService(DistributedAlgorithmNodeService, {
+      ping: (_call, cb) => cb(null, { error: false, msg: "pong" }),
+      executeMessage: (call, cb) => {
+        this.onMessage(call.request);
+        cb(null, {});
+      }
+    });
+    this.server = server;
+    return new Promise((resolve, reject) => {
+      server.bindAsync(
+        this.address,
+        ServerCredentials.createInsecure(),
+        (err) => err ? reject(err) : resolve()
+      );
+    });
+  }
+  /** Send a command message to a peer node and await its acknowledgement. */
+  send(peer, message) {
+    const client = new DistributedAlgorithmNodeClient(peer, credentials.createInsecure());
+    return new Promise((resolve, reject) => {
+      client.executeMessage(message, (err) => {
+        client.close();
+        if (err) reject(err);
+        else resolve();
+      });
+    });
+  }
+  /** Ping a peer node; resolves with its `Ack`. */
+  ping(peer) {
+    const client = new DistributedAlgorithmNodeClient(peer, credentials.createInsecure());
+    return new Promise((resolve, reject) => {
+      client.ping({}, (err, ack) => {
+        client.close();
+        if (err) reject(err);
+        else resolve(ack);
+      });
+    });
+  }
+  stop() {
+    return new Promise((resolve) => {
+      if (!this.server) return resolve();
+      this.server.tryShutdown(() => resolve());
+    });
+  }
+};
+
+// src/query-tokens.ts
+var LinkSchema = {
+  ATOM: "ATOM",
+  NODE: "NODE",
+  LINK: "LINK",
+  UNTYPED_VARIABLE: "VARIABLE",
+  LINK_TEMPLATE: "LINK_TEMPLATE"
+};
+var node = (name, type = "Symbol") => ({ kind: "node", type, name });
+var variable = (name) => ({ kind: "var", name });
+var expr = (...children) => ({ kind: "expr", children });
+function hasVar(p) {
+  switch (p.kind) {
+    case "var":
+      return true;
+    case "node":
+    case "atom":
+      return false;
+    case "expr":
+      return p.children.some(hasVar);
+  }
+}
+function encodeQuery(p, linkType = "Expression") {
+  switch (p.kind) {
+    case "node":
+      return [LinkSchema.NODE, p.type, p.name];
+    case "var":
+      return [LinkSchema.UNTYPED_VARIABLE, p.name];
+    case "atom":
+      return [LinkSchema.ATOM, p.handle];
+    case "expr": {
+      const head = hasVar(p) ? LinkSchema.LINK_TEMPLATE : LinkSchema.LINK;
+      const tokens = [head, linkType, String(p.children.length)];
+      for (const c of p.children) tokens.push(...encodeQuery(c, linkType));
+      return tokens;
+    }
+  }
+}
+
+// src/answer.ts
+var PROXY_COMMAND = "bus_command_proxy";
+var ANSWER_BUNDLE = "answer_bundle";
+var FINISHED = "finished";
+var ABORT = "abort";
+function unwrapProxyMessage(args) {
+  if (args.length === 0) throw new Error("empty bus_command_proxy args");
+  return { command: args[args.length - 1], args: args.slice(0, -1) };
+}
+function parseQueryAnswer(token) {
+  const s = token;
+  let i = 0;
+  const word = (what) => {
+    while (i < s.length && s[i] === " ") i++;
+    const start = i;
+    while (i < s.length && s[i] !== " ") i++;
+    if (i === start)
+      throw new Error(`malformed query answer: expected ${what} at offset ${start} in <${s}>`);
+    return s.slice(start, i);
+  };
+  const count = (what) => {
+    const w = word(what);
+    const n = Number(w);
+    if (!Number.isInteger(n) || n < 0)
+      throw new Error(`malformed query answer: expected ${what} count, got <${w}> in <${s}>`);
+    return n;
+  };
+  const mettaExpr = () => {
+    while (i < s.length && s[i] === " ") i++;
+    const start = i;
+    if (s[i] === "(") {
+      let depth = 0;
+      let inStr = false;
+      let esc = false;
+      for (; i < s.length; i++) {
+        const c = s[i];
+        if (inStr) {
+          if (esc) esc = false;
+          else if (c === "\\") esc = true;
+          else if (c === '"') inStr = false;
+        } else if (c === '"') inStr = true;
+        else if (c === "(") depth++;
+        else if (c === ")" && --depth === 0) {
+          i++;
+          break;
+        }
+      }
+      if (depth !== 0)
+        throw new Error(`malformed query answer: unbalanced parens in metta expr <${s}>`);
+      return s.slice(start, i);
+    }
+    if (s[i] === '"') {
+      i++;
+      let esc = false;
+      let closed = false;
+      for (; i < s.length; i++) {
+        const c = s[i];
+        if (esc) esc = false;
+        else if (c === "\\") esc = true;
+        else if (c === '"') {
+          i++;
+          closed = true;
+          break;
+        }
+      }
+      if (!closed)
+        throw new Error(`malformed query answer: unterminated string in metta expr <${s}>`);
+      return s.slice(start, i);
+    }
+    return word("metta expr");
+  };
+  word("strength");
+  word("importance");
+  const handles = [];
+  const numHandles = count("handles");
+  for (let k = 0; k < numHandles; k++) handles.push(word("handle"));
+  const assignment = {};
+  const asgSize = count("assignment size");
+  for (let k = 0; k < asgSize; k++) {
+    const label = word("variable label");
+    assignment[label] = word("variable handle");
+  }
+  const metta = {};
+  const mettaSize = count("metta-map size");
+  for (let k = 0; k < mettaSize; k++) {
+    const handle = word("metta handle");
+    metta[handle] = mettaExpr();
+  }
+  return { assignment, handles, metta };
+}
+function collectAnswers(messages) {
+  const answers = [];
+  let finished = false;
+  let aborted = false;
+  for (const m of messages) {
+    if (m.command !== PROXY_COMMAND) continue;
+    const inner = unwrapProxyMessage(m.args);
+    switch (inner.command) {
+      case ANSWER_BUNDLE:
+        for (const tok of inner.args) answers.push(parseQueryAnswer(tok));
+        break;
+      case FINISHED:
+        finished = true;
+        break;
+      case ABORT:
+        aborted = true;
+        break;
+      default:
+        break;
+    }
+  }
+  return { answers, finished, aborted };
+}
+
+// src/query-client.ts
+import { Server as Server2, ServerCredentials as ServerCredentials2, credentials as credentials2 } from "@grpc/grpc-js";
+
+// src/gen/atom_space_node.ts
+import { BinaryReader as BinaryReader3, BinaryWriter as BinaryWriter3 } from "@bufbuild/protobuf/wire";
+import {
+  makeGenericClientConstructor as makeGenericClientConstructor2
+} from "@grpc/grpc-js";
+function createBaseMessageData2() {
+  return { command: "", args: [], sender: "", isBroadcast: false, visitedRecipients: [] };
+}
+var MessageData2 = {
+  encode(message, writer = new BinaryWriter3()) {
+    if (message.command !== "") {
+      writer.uint32(10).string(message.command);
+    }
+    for (const v of message.args) {
+      writer.uint32(18).string(v);
+    }
+    if (message.sender !== "") {
+      writer.uint32(26).string(message.sender);
+    }
+    if (message.isBroadcast !== false) {
+      writer.uint32(32).bool(message.isBroadcast);
+    }
+    for (const v of message.visitedRecipients) {
+      writer.uint32(42).string(v);
+    }
+    return writer;
+  },
+  decode(input, length) {
+    const reader = input instanceof BinaryReader3 ? input : new BinaryReader3(input);
+    const end = length === void 0 ? reader.len : reader.pos + length;
+    const message = createBaseMessageData2();
+    while (reader.pos < end) {
+      const tag = reader.uint32();
+      switch (tag >>> 3) {
+        case 1: {
+          if (tag !== 10) {
+            break;
+          }
+          message.command = reader.string();
+          continue;
+        }
+        case 2: {
+          if (tag !== 18) {
+            break;
+          }
+          message.args.push(reader.string());
+          continue;
+        }
+        case 3: {
+          if (tag !== 26) {
+            break;
+          }
+          message.sender = reader.string();
+          continue;
+        }
+        case 4: {
+          if (tag !== 32) {
+            break;
+          }
+          message.isBroadcast = reader.bool();
+          continue;
+        }
+        case 5: {
+          if (tag !== 42) {
+            break;
+          }
+          message.visitedRecipients.push(reader.string());
+          continue;
+        }
+      }
+      if ((tag & 7) === 4 || tag === 0) {
+        break;
+      }
+      reader.skip(tag & 7);
+    }
+    return message;
+  },
+  fromJSON(object) {
+    return {
+      command: isSet3(object.command) ? globalThis.String(object.command) : "",
+      args: globalThis.Array.isArray(object?.args) ? object.args.map((e) => globalThis.String(e)) : [],
+      sender: isSet3(object.sender) ? globalThis.String(object.sender) : "",
+      isBroadcast: isSet3(object.isBroadcast) ? globalThis.Boolean(object.isBroadcast) : isSet3(object.is_broadcast) ? globalThis.Boolean(object.is_broadcast) : false,
+      visitedRecipients: globalThis.Array.isArray(object?.visitedRecipients) ? object.visitedRecipients.map((e) => globalThis.String(e)) : globalThis.Array.isArray(object?.visited_recipients) ? object.visited_recipients.map((e) => globalThis.String(e)) : []
+    };
+  },
+  toJSON(message) {
+    const obj = {};
+    if (message.command !== "") {
+      obj.command = message.command;
+    }
+    if (message.args?.length) {
+      obj.args = message.args;
+    }
+    if (message.sender !== "") {
+      obj.sender = message.sender;
+    }
+    if (message.isBroadcast !== false) {
+      obj.isBroadcast = message.isBroadcast;
+    }
+    if (message.visitedRecipients?.length) {
+      obj.visitedRecipients = message.visitedRecipients;
+    }
+    return obj;
+  },
+  create(base) {
+    return MessageData2.fromPartial(base ?? {});
+  },
+  fromPartial(object) {
+    const message = createBaseMessageData2();
+    message.command = object.command ?? "";
+    message.args = object.args?.map((e) => e) || [];
+    message.sender = object.sender ?? "";
+    message.isBroadcast = object.isBroadcast ?? false;
+    message.visitedRecipients = object.visitedRecipients?.map((e) => e) || [];
+    return message;
+  }
+};
+var AtomSpaceNodeService = {
+  ping: {
+    path: "/dasproto.AtomSpaceNode/ping",
+    requestStream: false,
+    responseStream: false,
+    requestSerialize: (value) => Buffer.from(Empty.encode(value).finish()),
+    requestDeserialize: (value) => Empty.decode(value),
+    responseSerialize: (value) => Buffer.from(Ack.encode(value).finish()),
+    responseDeserialize: (value) => Ack.decode(value)
+  },
+  executeMessage: {
+    path: "/dasproto.AtomSpaceNode/execute_message",
+    requestStream: false,
+    responseStream: false,
+    requestSerialize: (value) => Buffer.from(MessageData2.encode(value).finish()),
+    requestDeserialize: (value) => MessageData2.decode(value),
+    responseSerialize: (value) => Buffer.from(Empty.encode(value).finish()),
+    responseDeserialize: (value) => Empty.decode(value)
+  }
+};
+var AtomSpaceNodeClient = makeGenericClientConstructor2(
+  AtomSpaceNodeService,
+  "dasproto.AtomSpaceNode"
+);
+function isSet3(value) {
+  return value !== null && value !== void 0;
+}
+
+// src/query-client.ts
+function paramTokens(opts) {
+  const out = [];
+  if (opts.populateMettaMapping) out.push("populate_metta_mapping", "bool", "true");
+  return out;
+}
+var serialCounter = 0;
+async function queryPatternMatching(opts) {
+  const { agentAddress, pattern, context = "", timeoutMs = 8e3 } = opts;
+  const proxyHost = opts.proxyHost ?? "127.0.0.1";
+  const received = [];
+  const server = new Server2();
+  server.addService(AtomSpaceNodeService, {
+    ping: (_c, cb) => cb(null, { error: false, msg: "PING" }),
+    executeMessage: (call, cb) => {
+      received.push({ command: call.request.command, args: call.request.args });
+      cb(null, {});
+    }
+  });
+  let bound = false;
+  try {
+    const port = await new Promise(
+      (res, rej) => server.bindAsync(
+        `${proxyHost}:0`,
+        ServerCredentials2.createInsecure(),
+        (e, p) => e ? rej(e) : res(p)
+      )
+    );
+    bound = true;
+    const proxyAddress = `${proxyHost}:${port}`;
+    const serial = String(serialCounter++);
+    const queryTokens = encodeQuery(pattern);
+    const params = paramTokens(opts);
+    const args = [
+      proxyAddress,
+      serial,
+      proxyAddress,
+      String(params.length),
+      ...params,
+      context,
+      String(queryTokens.length),
+      ...queryTokens
+    ];
+    const client = new AtomSpaceNodeClient(agentAddress, credentials2.createInsecure());
+    try {
+      await new Promise(
+        (res, rej) => client.executeMessage(
+          {
+            command: "pattern_matching_query",
+            args,
+            sender: proxyAddress,
+            isBroadcast: false,
+            visitedRecipients: []
+          },
+          (e) => e ? rej(e) : res()
+        )
+      );
+    } finally {
+      client.close();
+    }
+    const deadline = Date.now() + timeoutMs;
+    const done = () => received.some((m) => {
+      if (m.command !== PROXY_COMMAND) return false;
+      const c = unwrapProxyMessage(m.args).command;
+      return c === FINISHED || c === ABORT;
+    });
+    while (Date.now() < deadline && !done()) await new Promise((r) => setTimeout(r, 100));
+  } finally {
+    if (bound) await new Promise((r) => server.tryShutdown(() => r()));
+    else server.forceShutdown();
+  }
+  return collectAnswers(received);
+}
+
+// src/async-space.ts
+import {
+  addValRaw,
+  emptyBindings,
+  instantiate,
+  parse,
+  standardTokenizer
+} from "@metta-ts/core";
+function escapeDasString(s) {
+  return s.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+}
+function atomToPattern(a) {
+  switch (a.kind) {
+    case "sym":
+      return node(a.name);
+    case "var":
+      return variable(a.name);
+    case "expr":
+      return expr(...a.items.map(atomToPattern));
+    case "gnd": {
+      const v = a.value;
+      switch (v.g) {
+        case "str":
+          return node(`"${escapeDasString(v.s)}"`);
+        case "int":
+        case "float":
+          return node(String(v.n));
+        case "bool":
+          return node(v.b ? "True" : "False");
+        default:
+          throw new Error(
+            `atomToPattern: grounded value of kind '${v.g}' has no DAS query encoding`
+          );
+      }
+    }
+  }
+}
+var TK = standardTokenizer();
+var DasLiveSpace = class {
+  constructor(agentAddress, proxyHost = "127.0.0.1", timeoutMs = 8e3) {
+    this.agentAddress = agentAddress;
+    this.timeoutMs = timeoutMs;
+    this.proxyHost = proxyHost.includes(":") ? proxyHost.slice(0, proxyHost.indexOf(":")) : proxyHost;
+  }
+  agentAddress;
+  timeoutMs;
+  proxyHost;
+  async queryAsync(pattern) {
+    const { answers, finished, aborted } = await queryPatternMatching({
+      proxyHost: this.proxyHost,
+      agentAddress: this.agentAddress,
+      pattern: atomToPattern(pattern),
+      populateMettaMapping: true,
+      timeoutMs: this.timeoutMs
+    });
+    if (aborted) throw new Error("DAS query aborted by the agent");
+    if (!finished)
+      throw new Error(`DAS query did not finish within ${this.timeoutMs}ms (incomplete results)`);
+    return answers.map((ans) => {
+      let b = emptyBindings;
+      for (const [label, handle] of Object.entries(ans.assignment)) {
+        const text = ans.metta[handle];
+        if (text === void 0)
+          throw new Error(`DAS answer has no MeTTa text for $${label} (handle ${handle})`);
+        const atom = parse(text, TK);
+        if (atom === void 0)
+          throw new Error(`DAS answer MeTTa text for $${label} did not parse: <${text}>`);
+        b = addValRaw(b, label, atom);
+      }
+      return b;
+    });
+  }
+};
+async function matchAsync(space, pattern, template = pattern) {
+  const bindings = await space.queryAsync(pattern);
+  return bindings.map((b) => instantiate(b, template));
+}
+export {
+  ABORT,
+  ANSWER_BUNDLE,
+  BusCommand,
+  BusNode,
+  DasLiveSpace,
+  DasSpace,
+  FINISHED,
+  MockTransport,
+  PROXY_COMMAND,
+  atomToPattern,
+  collectAnswers,
+  compositeHash,
+  computeHash,
+  encodeQuery,
+  expr,
+  expressionHash,
+  matchAsync,
+  namedTypeHash,
+  node,
+  parseQueryAnswer,
+  queryPatternMatching,
+  terminalHash,
+  unwrapProxyMessage,
+  variable
+};

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@metta-ts/das-client",
+  "version": "1.0.0",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@grpc/grpc-js": "^1.14.4",
+    "@bufbuild/protobuf": "^2.2.3",
+    "@metta-ts/core": "1.0.0"
+  },
+  "devDependencies": {
+    "ts-proto": "^2.11.8"
+  },
+  "author": "MesTTo",
+  "engines": {
+    "node": ">=20"
+  },
+  "sideEffects": false,
+  "module": "./dist/index.js",
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "Client for SingularityNET Distributed AtomSpace (DAS) for MeTTa TS, over a Connect gateway.",
+  "keywords": [
+    "metta",
+    "hyperon",
+    "das",
+    "distributed-atomspace",
+    "singularitynet"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MesTTo/Meta-TypeScript-Talk.git",
+    "directory": "packages/das-client"
+  },
+  "homepage": "https://github.com/MesTTo/Meta-TypeScript-Talk#readme",
+  "bugs": {
+    "url": "https://github.com/MesTTo/Meta-TypeScript-Talk/issues"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "gen": "protoc --plugin=protoc-gen-ts_proto=./node_modules/.bin/protoc-gen-ts_proto --ts_proto_out=./src/gen --ts_proto_opt=outputServices=grpc-js,esModuleInterop=true,forceLong=string -I proto proto/*.proto"
+  }
+}