@dot-agent/kernel-dsl 0.1.0

package/LICENSE

@@ -0,0 +1,178 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship made available under
+      the License, as indicated by a copyright notice that is included in
+      or attached to the work (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean, as submitted to the Licensor for inclusion
+      in the Work by the copyright owner or by an individual or Legal Entity
+      authorized to submit on behalf of the copyright owner. For the purposes
+      of this definition, "submitted" means any form of electronic, verbal,
+      or written communication sent to the Licensor or its representatives,
+      including but not limited to communication on electronic mailing lists,
+      source code control systems, and issue tracking systems that are managed
+      by, or on behalf of, the Licensor for the purpose of discussing and
+      improving the Work, but excluding communication that is conspicuously
+      marked or designated in writing by the copyright owner as "Not a
+      Contribution."
+
+      "Contributor" shall mean Licensor and any Legal Entity on behalf of
+      whom a Contribution has been received by the Licensor and included
+      within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent licenses granted to
+      You under this License for that Work shall terminate as of the date
+      such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or Derivative
+          Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, You must include a readable copy of the
+          attribution notices contained within such NOTICE file, in
+          at least one of the following places: within a NOTICE text
+          file distributed as part of the Derivative Works; within
+          the Source form or documentation, if provided along with the
+          Derivative Works; or, within a display generated by the
+          Derivative Works, if and wherever such third-party notices
+          normally appear. The contents of the NOTICE file are for
+          informational purposes only and do not modify the License.
+          You may add Your own attribution notices within Derivative
+          Works that You distribute, alongside or as an addendum to
+          the NOTICE text from the Work, provided that such additional
+          attribution notices cannot be construed as modifying the License.
+
+      You may add Your own license statement for Your modifications and
+      may provide additional grant of rights to use, copy, modify, merge,
+      publish, distribute, sublicense, and/or sell copies of the
+      Contribution, either in combined form with the Work or separate from
+      the Work. If You choose to provide additional grant of rights, You
+      must do so in a manner consistent with the terms of this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or reproducing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or exemplary damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or all other
+      commercial damages or losses), even if such Contributor has been
+      advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright (c) 2026 Danilo Borges (https://github.com/daniloborges)
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,244 @@
+# @dot-agent/kernel-dsl
+
+Execution engine for the **agent behavior DSL** (`.description` and `.behavior` files), written in Rust and compiled to **WebAssembly**. Implements a Finite State Machine (FSM) that interprets `.behavior` files according to the full dot-agent-spec, running entirely in-memory on the client side (browser or Node.js).
+
+## Quick Start
+
+### Installation
+
+```bash
+npm install @dot-agent/kernel-dsl
+```
+
+### Basic Usage
+
+```javascript
+import { AgentDSLKernel, init } from '@dot-agent/kernel-dsl';
+
+// Initialize WASM once
+await init();
+
+// Create kernel instance
+const kernel = new AgentDSLKernel();
+
+// Load behavior DSL
+const behavior = `
+state welcome
+  goal "Help the user"
+  interact
+  on intent "help" transition to helping
+
+state helping
+  goal "Provide assistance"
+`;
+
+kernel.load_behavior(behavior);
+
+// Get current state
+console.log(kernel.get_current_state()); // "welcome"
+
+// Listen to state changes and effects
+kernel.observe((effect) => {
+  console.log('Effect:', effect);
+  
+  switch (effect.type) {
+    case 'goal':
+      console.log('Goal:', effect.text);
+      break;
+    case 'transition':
+      console.log('Transitioned to:', effect.to);
+      break;
+  }
+});
+
+// Send intents
+kernel.send_intent("help");
+
+// Get state graph
+const graph = kernel.get_graph();
+console.log('States:', graph.states);
+console.log('Transitions:', graph.transitions);
+```
+
+### React Integration
+
+```typescript
+import { AgentDSLKernel, init } from '@dot-agent/kernel-dsl';
+import { useEffect, useState } from 'react';
+
+export function AgentPanel() {
+  const [engine, setEngine] = useState<AgentDSLKernel | null>(null);
+  const [currentState, setCurrentState] = useState('');
+
+  useEffect(() => {
+    (async () => {
+      await init();
+      const kernel = new AgentDSLKernel();
+      
+      kernel.observe((effect) => {
+        if (effect.type === 'transition') {
+          setCurrentState(effect.to);
+        }
+      });
+
+      setEngine(kernel);
+    })();
+  }, []);
+
+  if (!engine) return <div>Loading...</div>;
+
+  return (
+    <div>
+      <p>Current State: {currentState}</p>
+      <button onClick={() => engine.send_intent('help')}>Help</button>
+    </div>
+  );
+}
+```
+
+## WASM Runtime Requirements
+
+The kernel-dsl WASM binary requires a complete runtime environment. See [`WASM_SHIM_ARCHITECTURE.md`](./WASM_SHIM_ARCHITECTURE.md) for:
+- Why a shim is necessary
+- Complete list of 31 required functions
+- How to extend implementations (time, random, environment)
+- Post-build patching process
+
+**Note**: Initialization is handled automatically by the `init()` function. No manual setup needed.
+
+## Architecture
+
+```
+src/
+├── lib.rs              — Public WASM API (#[wasm_bindgen], no business logic)
+├── effect.rs           — Effect enum + MemValue (serialized return types for JS)
+├── parser/
+│   ├── mod.rs          — parse_behavior(text) → BehaviorFile via tree-sitter
+│   └── ast.rs          — AST types (BehaviorFile, StateDef, Statement, …) with serde
+└── engine/
+    ├── mod.rs          — AgentDSLKernel: orchestrates parser + FSM + memory
+    ├── fsm.rs          — State execution, intent dispatch, conditionals, get_graph()
+    └── memory.rs       — MemoryStore: 4 domains (context/session/worksession/user)
+
+build.rs               — Code generation: extracts node kinds from tree-sitter grammar
+```
+
+The parser uses **tree-sitter** for robust parsing. The grammar is maintained in the [`dot-agent-tree-sitter`](https://github.com/daniloborges/dot-agent-tree-sitter) crate. `build.rs` automatically extracts node kinds from `tree-sitter/node-types.json` to keep parsing logic in sync with the grammar — when the grammar changes, simply update the tree-sitter crate version and rebuild.
+
+## Supported constructs
+
+The parser and FSM cover the full `.agent DSL`:
+
+| Construct | Example |
+|-----------|---------|
+| State | `state responsive` |
+| Goal / Guide / Teach | `goal "text"` |
+| Interact | `interact` |
+| Inline intent | `on intent "planning" transition to planning` |
+| Block intent | `on intent "search"` + indented block |
+| Offtopic | `on offtopic` + block |
+| Global event | `on event "session.ended"` + block |
+| Memory assign | `set context.phase = "planning"` |
+| Compound assign | `+=` / `-=` across all domains |
+| Conditional | `if session.ready == true` + optional `else` |
+| Transition | `transition to planning` |
+| Run | `run script "file.js" silent` / `run subagent "agent.behavior" in background` |
+| Temporal | `after 3 prompts guide "…"` |
+| Parallel | `parallel` + block |
+| UI | `apply css "…"` / `remove html "…"` |
+| Merge | `merge "other.behavior"` (recorded in AST, resolved by external runtime) |
+| Async completion | `on complete` / `on failed` + block |
+
+## Build
+
+```bash
+rustup target add wasm32-unknown-unknown
+cargo install wasm-pack
+wasm-pack build --target bundler
+```
+
+The generated `pkg/` directory is consumed via the package root:
+
+```bash
+npm install @dot-agent/kernel-dsl
+```
+
+## API
+
+All methods return a **JSON array of `Effect` objects**, letting JS react to flow actions without polling.
+
+```typescript
+const engine = new AgentDSLKernel();
+
+// Load a .behavior file and receive the entry effects of the first state
+const effects = engine.load_behavior(behaviorText);
+// → [{ type: "goal", text: "…" }, { type: "request_interact" }]
+
+// Dispatch an intent (name classified by the LLM layer)
+engine.send_intent("planning");
+
+// Flow handlers
+engine.send_offtopic();
+engine.send_event("session.ended");
+
+// Async operation completion
+engine.send_complete();
+engine.send_failed();
+
+// Temporal triggers — call once per processed prompt
+engine.tick_prompt();
+
+// State reads
+engine.get_current_state();  // string
+engine.get_valid_intents();  // Array<string>
+
+// Memory
+engine.get_memory();                          // [{ domain, key, value }]
+engine.set_memory("session", "lang", '"pt"'); // value as JSON string
+
+// State graph (for VS Code Flow Graph panel)
+engine.get_graph();
+// → { states: ["responsive", "planning"], transitions: [{from, to, label}], current: "responsive" }
+```
+
+### Effect types
+
+```typescript
+type Effect =
+  | { type: "goal";             text: string }
+  | { type: "guide";            text: string }
+  | { type: "teach";            text: string }
+  | { type: "request_interact" }
+  | { type: "transition";       from: string; to: string }
+  | { type: "run_script";       target: string; label: string | null; silent: boolean }
+  | { type: "run_subagent";     target: string; label: string | null; background: boolean }
+  | { type: "run_tool";         target: string; label: string | null }
+  | { type: "set_memory";       domain: string; key: string; value: string | number | boolean | null }
+  | { type: "apply_css";        value: string }
+  | { type: "remove_css";       value: string }
+  | { type: "apply_html";       value: string }
+  | { type: "remove_html";      value: string }
+  | { type: "apply_video";      value: string }
+  | { type: "remove_video";     value: string }
+  | { type: "parse_error";      message: string }
+```
+
+For the full API reference — all effect types, handler implementation examples, memory domains, TypeScript types, and a React hook — see [API.md](API.md).
+
+### Dynamic import (Next.js / SSR)
+
+```javascript
+import("@dot-agent/kernel-dsl").then(module => {
+  const engine = new module.AgentDSLKernel();
+  const effects = engine.load_behavior(behaviorText);
+  console.log(effects);
+});
+```
+
+---
+
+## License
+
+Copyright (c) 2026 Danilo Borges (https://github.com/daniloborges)
+
+Licensed under the **Apache License, Version 2.0** — see [`LICENSE`](LICENSE).

package/index.js

@@ -0,0 +1,111 @@
+let _initialized = false;
+let _module = null;
+
+// Complete WASI + Rust runtime shim - 31 functions required
+const wasiShim = {
+  // WASI file descriptor operations (5)
+  fd_write: () => 0,
+  fd_close: () => 0,
+  fd_seek: () => 0,
+  fd_prestat_get: () => 0,
+  fd_prestat_dir_name: () => 0,
+
+  // WASI environment (2)
+  environ_get: () => 0,
+  environ_sizes_get: () => 0,
+
+  // WASI time (1)
+  clock_time_get: () => 0,
+
+  // WASI misc (1)
+  random_get: () => 0,
+  proc_exit: () => 0,
+
+  // Rust UB Sanitizer handlers (11)
+  __ubsan_handle_type_mismatch_v1: () => 0,
+  __ubsan_handle_alignment_assumption: () => 0,
+  __ubsan_handle_out_of_bounds: () => 0,
+  __ubsan_handle_nonnull_arg: () => 0,
+  __ubsan_handle_load_invalid_value: () => 0,
+  __ubsan_handle_builtin_unreachable: () => 0,
+  __ubsan_handle_add_overflow: () => 0,
+  __ubsan_handle_sub_overflow: () => 0,
+  __ubsan_handle_mul_overflow: () => 0,
+  __ubsan_handle_divrem_overflow: () => 0,
+  __ubsan_handle_shift_out_of_bounds: () => 0,
+  __ubsan_handle_pointer_overflow: () => 0,
+
+  // wasm-bindgen JS interop (8)
+  __wbg_call_9c758de292015997: () => 0,
+  __wbg_new_d90091b82fdf5b91: () => 0,
+  __wbg_new_ce1ab61c1c2b300d: () => 0,
+  __wbg_push_a6822215aa43e71c: () => 0,
+  __wbg_set_6be42768c690e380: () => 0,
+  __wbg_set_dca99999bba88a9a: () => 0,
+  __wbg___wbindgen_throw_1506f2235d1bdba0: () => 0,
+
+  // wasm-bindgen internal (3)
+  __wbindgen_init_externref_table: () => 0,
+  __wbindgen_cast_0000000000000001: () => 0,
+  __wbindgen_cast_0000000000000002: () => 0,
+};
+
+export class AgentDSLKernel {
+  constructor() {
+    if (!_initialized) throw new Error('Must call init() first');
+    this._kernel = new _module.AgentDSLKernel();
+  }
+
+  get_current_state() { return this._kernel.get_current_state(); }
+  get_graph() { return this._kernel.get_graph(); }
+  get_memory() { return this._kernel.get_memory(); }
+  get_valid_intents() { return this._kernel.get_valid_intents(); }
+  load_behavior(text) { return this._kernel.load_behavior(text); }
+  observe(callback) { return this._kernel.observe(callback); }
+  send_complete() { return this._kernel.send_complete(); }
+  send_event(event) { return this._kernel.send_event(event); }
+  send_failed() { return this._kernel.send_failed(); }
+  send_fallback() { return this._kernel.send_fallback(); }
+  send_intent(intent) { return this._kernel.send_intent(intent); }
+  send_offtopic() { return this._kernel.send_offtopic(); }
+  tick_prompt() { return this._kernel.tick_prompt(); }
+  free() { return this._kernel.free(); }
+}
+
+export async function init() {
+  if (_initialized) return;
+
+  try {
+    const bgModule = await import('./pkg/dot_agent_kernel_dsl_bg.js');
+
+    // Load WASM buffer: fetch in browser, fs.readFile in Node.js
+    let wasmBuffer;
+    if (typeof window !== 'undefined') {
+      // Browser environment
+      const wasmPath = new URL('./pkg/dot_agent_kernel_dsl_bg.wasm', import.meta.url);
+      const wasmResponse = await fetch(wasmPath);
+      wasmBuffer = await wasmResponse.arrayBuffer();
+    } else {
+      // Node.js environment
+      const { readFile } = await import('node:fs/promises');
+      const { fileURLToPath } = await import('node:url');
+      const wasmPath = fileURLToPath(new URL('./pkg/dot_agent_kernel_dsl_bg.wasm', import.meta.url));
+      wasmBuffer = await readFile(wasmPath);
+    }
+
+    const importObject = {
+      env: wasiShim,
+      wasi_snapshot_preview1: wasiShim,
+      './dot_agent_kernel_dsl_bg.js': { ...bgModule }
+    };
+
+    const wasmModule = await WebAssembly.instantiate(wasmBuffer, importObject);
+    bgModule.__wbg_set_wasm(wasmModule.instance.exports);
+    _module = await import('./pkg/dot_agent_kernel_dsl.js');
+
+    _initialized = true;
+  } catch (err) {
+    console.error('Failed to initialize wasm:', err);
+    throw err;
+  }
+}

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@dot-agent/kernel-dsl",
+  "version": "0.1.0",
+  "description": "WASM kernel for parsing and executing the agent behavior DSL",
+  "type": "module",
+  "main": "./index.js",
+  "types": "./pkg/dot_agent_kernel_dsl.d.ts",
+  "license": "Apache-2.0",
+  "author": {
+    "name": "Danilo Borges",
+    "email": "contato@daniloborg.es",
+    "url": "https://daniloborg.es"
+  },
+  "contributors": [
+    {
+      "name": "Danilo Borges",
+      "email": "contato@daniloborg.es"
+    }
+  ],
+  "homepage": "https://github.com/dot-agent-spec/kernel-dsl",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dot-agent-spec/kernel-dsl"
+  },
+  "bugs": {
+    "url": "https://github.com/dot-agent-spec/kernel-dsl/issues"
+  },
+  "keywords": [
+    "wasm",
+    "agent",
+    "dsl",
+    "behavior",
+    "fsm",
+    "state-machine",
+    "parser",
+    "webassembly"
+  ],
+  "files": [
+    "index.js",
+    "scripts/discover-wasm-imports.js",
+    "scripts/patch-wasm-bindgen.js",
+    "pkg/dot_agent_kernel_dsl.js",
+    "pkg/dot_agent_kernel_dsl.d.ts",
+    "pkg/dot_agent_kernel_dsl_bg.wasm",
+    "pkg/dot_agent_kernel_dsl_bg.wasm.d.ts",
+    "pkg/package.json"
+  ],
+  "exports": {
+    ".": {
+      "import": "./index.js",
+      "types": "./pkg/dot_agent_kernel_dsl.d.ts"
+    }
+  },
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "scripts": {
+    "build": "./scripts/build-wasm.sh && node scripts/patch-wasm-bindgen.js",
+    "build:release": "RELEASE=true ./scripts/build-wasm.sh && node scripts/patch-wasm-bindgen.js",
+    "patch": "node -e \"const fs=require('fs'),p=require('./pkg/package.json');p.name='@dot-agent/kernel-dsl';p.publishConfig={access:'public'};fs.writeFileSync('./pkg/package.json',JSON.stringify(p,null,2)+'\\n')\"",
+    "test:node": "node --test tests/node-compat.test.js",
+    "prepublishOnly": "npm run build:release && npm run patch"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+  }
+}

package/pkg/dot_agent_kernel_dsl.d.ts

@@ -0,0 +1,95 @@
+/* tslint:disable */
+/* eslint-disable */
+
+export class AgentDSLKernel {
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Return the name of the current state.
+     */
+    get_current_state(): string;
+    /**
+     * Return the state graph as { states, transitions, current }.
+     *
+     * Use this to render the Flow Graph panel in VS Code or any diagram tool.
+     */
+    get_graph(): any;
+    /**
+     * Return the full memory store as a JSON array of { domain, key, value } entries.
+     */
+    get_memory(): any;
+    /**
+     * Return an array of intent strings declared in the current state.
+     *
+     * Use this to build the list of valid intent names to pass to the LLM classifier.
+     */
+    get_valid_intents(): Array<any>;
+    /**
+     * Parse and load a .behavior DSL text.
+     *
+     * Fires the observer for each entry effect of the first state (typically goal +
+     * request_interact). Also returns the effects array for imperative call sites.
+     * On parse error, fires and returns a single ParseError effect.
+     */
+    load_behavior(text: string): any;
+    constructor();
+    /**
+     * Register a callback that WASM will call once per Effect as they are produced.
+     *
+     * This is the primary integration point — the equivalent of the importObject in a
+     * raw WebAssembly.instantiate call. The callback receives a single Effect object
+     * per invocation and must implement all WASM→JS directives (goal, guide, teach,
+     * run_script, run_subagent, run_tool, apply_css, …).
+     *
+     * Only one observer can be active at a time; calling observe() again replaces it.
+     */
+    observe(callback: Function): void;
+    /**
+     * Signal that the last async operation (run_script, run_subagent, run_tool) completed successfully.
+     *
+     * Fires the observer with the effects of the current state's `on complete` block.
+     */
+    send_complete(): any;
+    /**
+     * Signal that the runtime could not resolve the current action.
+     * Dispatch a named global event (e.g. "session.ended", "script.done").
+     *
+     * Matches top-level `on event "…"` declarations. Use this to notify the FSM
+     * when an async operation triggered by run_script / run_subagent / run_tool completes.
+     */
+    send_event(event: string): any;
+    /**
+     * Signal that the last async operation (run_script, run_subagent, run_tool) failed.
+     *
+     * Fires the observer with the effects of the current state's `on failed` block.
+     */
+    send_failed(): any;
+    /**
+     * Dispatch a named intent to the FSM.
+     *
+     * Call this after the LLM classifies the user's message into an intent name that
+     * matches one of the `on intent "…"` declarations in the current state.
+     * Fires the observer with transition + any entry effects of the new state.
+     */
+    send_intent(intent: string): any;
+    /**
+     * Signal that the current message is off-topic.
+     *
+     * Fires the observer with the effects of the current state's `on offtopic` block.
+     */
+    send_offtopic(): any;
+    /**
+     * Set a value in the memory store from JS.
+     *
+     * domain: "context" | "session" | "worksession" | "user"
+     * value_json: value serialized as a JSON primitive ("text", 42, true, null)
+     */
+    set_memory(domain: string, key: string, value_json: string): void;
+    /**
+     * Notify the engine that a prompt turn was processed.
+     *
+     * Call once per LLM completion. Triggers any matching `after N prompts` handlers
+     * in the current state, firing their effects through the observer.
+     */
+    tick_prompt(): any;
+}

package/pkg/dot_agent_kernel_dsl.js

@@ -0,0 +1,6 @@
+/* @ts-self-types"./dot_agent_kernel_dsl.d.ts" */
+/* MODIFIED: WASM is loaded manually by index.js to avoid webpack parse errors */
+
+export {
+    AgentDSLKernel
+} from "./dot_agent_kernel_dsl_bg.js";

package/pkg/dot_agent_kernel_dsl_bg.wasm.d.ts

@@ -0,0 +1,25 @@
+/* tslint:disable */
+/* eslint-disable */
+export const memory: WebAssembly.Memory;
+export const __wbg_agentdslkernel_free: (a: number, b: number) => void;
+export const agentdslkernel_get_current_state: (a: number) => [number, number];
+export const agentdslkernel_get_graph: (a: number) => any;
+export const agentdslkernel_get_memory: (a: number) => any;
+export const agentdslkernel_get_valid_intents: (a: number) => any;
+export const agentdslkernel_load_behavior: (a: number, b: number, c: number) => any;
+export const agentdslkernel_new: () => number;
+export const agentdslkernel_observe: (a: number, b: any) => void;
+export const agentdslkernel_send_complete: (a: number) => any;
+export const agentdslkernel_send_event: (a: number, b: number, c: number) => any;
+export const agentdslkernel_send_failed: (a: number) => any;
+export const agentdslkernel_send_intent: (a: number, b: number, c: number) => any;
+export const agentdslkernel_send_offtopic: (a: number) => any;
+export const agentdslkernel_set_memory: (a: number, b: number, c: number, d: number, e: number, f: number, g: number) => void;
+export const agentdslkernel_tick_prompt: (a: number) => any;
+export const __wbindgen_exn_store_command_export: (a: number) => void;
+export const __externref_table_alloc_command_export: () => number;
+export const __wbindgen_externrefs: WebAssembly.Table;
+export const __wbindgen_free_command_export: (a: number, b: number, c: number) => void;
+export const __wbindgen_malloc_command_export: (a: number, b: number) => number;
+export const __wbindgen_realloc_command_export: (a: number, b: number, c: number, d: number) => number;
+export const __wbindgen_start: () => void;

package/pkg/index.js

@@ -0,0 +1,99 @@
+let _initialized = false;
+let _module = null;
+
+// Complete WASI + Rust runtime shim - 31 functions required
+const wasiShim = {
+  // WASI file descriptor operations (5)
+  fd_write: () => 0,
+  fd_close: () => 0,
+  fd_seek: () => 0,
+  fd_prestat_get: () => 0,
+  fd_prestat_dir_name: () => 0,
+
+  // WASI environment (2)
+  environ_get: () => 0,
+  environ_sizes_get: () => 0,
+
+  // WASI time (1)
+  clock_time_get: () => 0,
+
+  // WASI misc (1)
+  random_get: () => 0,
+  proc_exit: () => 0,
+
+  // Rust UB Sanitizer handlers (11)
+  __ubsan_handle_type_mismatch_v1: () => 0,
+  __ubsan_handle_alignment_assumption: () => 0,
+  __ubsan_handle_out_of_bounds: () => 0,
+  __ubsan_handle_nonnull_arg: () => 0,
+  __ubsan_handle_load_invalid_value: () => 0,
+  __ubsan_handle_builtin_unreachable: () => 0,
+  __ubsan_handle_add_overflow: () => 0,
+  __ubsan_handle_sub_overflow: () => 0,
+  __ubsan_handle_mul_overflow: () => 0,
+  __ubsan_handle_divrem_overflow: () => 0,
+  __ubsan_handle_shift_out_of_bounds: () => 0,
+  __ubsan_handle_pointer_overflow: () => 0,
+
+  // wasm-bindgen JS interop (8)
+  __wbg_call_9c758de292015997: () => 0,
+  __wbg_new_d90091b82fdf5b91: () => 0,
+  __wbg_new_ce1ab61c1c2b300d: () => 0,
+  __wbg_push_a6822215aa43e71c: () => 0,
+  __wbg_set_6be42768c690e380: () => 0,
+  __wbg_set_dca99999bba88a9a: () => 0,
+  __wbg___wbindgen_throw_1506f2235d1bdba0: () => 0,
+
+  // wasm-bindgen internal (3)
+  __wbindgen_init_externref_table: () => 0,
+  __wbindgen_cast_0000000000000001: () => 0,
+  __wbindgen_cast_0000000000000002: () => 0,
+};
+
+export class AgentDSLKernel {
+  constructor() {
+    if (!_initialized) throw new Error('Must call init() first');
+    this._kernel = new _module.AgentDSLKernel();
+  }
+
+  get_current_state() { return this._kernel.get_current_state(); }
+  get_graph() { return this._kernel.get_graph(); }
+  get_memory() { return this._kernel.get_memory(); }
+  get_valid_intents() { return this._kernel.get_valid_intents(); }
+  load_behavior(text) { return this._kernel.load_behavior(text); }
+  observe(callback) { return this._kernel.observe(callback); }
+  send_complete() { return this._kernel.send_complete(); }
+  send_event(event) { return this._kernel.send_event(event); }
+  send_failed() { return this._kernel.send_failed(); }
+  send_fallback() { return this._kernel.send_fallback(); }
+  send_intent(intent) { return this._kernel.send_intent(intent); }
+  send_offtopic() { return this._kernel.send_offtopic(); }
+  tick_prompt() { return this._kernel.tick_prompt(); }
+  free() { return this._kernel.free(); }
+}
+
+export async function init() {
+  if (_initialized) return;
+
+  try {
+    const bgModule = await import('./pkg/dot_agent_kernel_dsl_bg.js');
+    const wasmPath = new URL('./pkg/dot_agent_kernel_dsl_bg.wasm', import.meta.url);
+    const wasmResponse = await fetch(wasmPath);
+    const wasmBuffer = await wasmResponse.arrayBuffer();
+    
+    const importObject = {
+      env: wasiShim,
+      wasi_snapshot_preview1: wasiShim,
+      './dot_agent_kernel_dsl_bg.js': { ...bgModule }
+    };
+    
+    const wasmModule = await WebAssembly.instantiate(wasmBuffer, importObject);
+    bgModule.__wbg_set_wasm(wasmModule.instance.exports);
+    _module = await import('./pkg/dot_agent_kernel_dsl.js');
+    
+    _initialized = true;
+  } catch (err) {
+    console.error('Failed to initialize wasm:', err);
+    throw err;
+  }
+}

package/pkg/package.json

@@ -0,0 +1,10 @@
+{
+  "name": "@dot-agent/kernel-dsl",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "dot_agent_kernel_dsl.js",
+  "types": "dot_agent_kernel_dsl.d.ts",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/scripts/discover-wasm-imports.js

@@ -0,0 +1,113 @@
+#!/usr/bin/env node
+/**
+ * WASM Import Discovery Tool
+ * 
+ * Discovers all functions required by the kernel-dsl WASM binary
+ * by attempting instantiation with a Proxy that tracks all accesses.
+ * 
+ * Usage: node scripts/discover-wasm-imports.js
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+const accessedFunctions = new Set();
+const functionCallCounts = new Map();
+
+// Create proxy to track all accessed functions
+const handler = {
+  get: (target, prop) => {
+    if (typeof prop === 'string') {
+      accessedFunctions.add(prop);
+      functionCallCounts.set(prop, (functionCallCounts.get(prop) || 0) + 1);
+    }
+    return (...args) => 0;
+  }
+};
+
+const wasiShimProxy = new Proxy({}, handler);
+
+async function discoverImports() {
+  try {
+    const wasmPath = path.join(__dirname, '../pkg/dot_agent_kernel_dsl_bg.wasm');
+    
+    if (!fs.existsSync(wasmPath)) {
+      console.error(`❌ WASM file not found: ${wasmPath}`);
+      console.error('Run: npm run build');
+      process.exit(1);
+    }
+
+    const wasmBuffer = fs.readFileSync(wasmPath);
+    
+    // Try to instantiate with proxy that captures all accesses
+    const importObject = {
+      env: wasiShimProxy,
+      wasi_snapshot_preview1: wasiShimProxy,
+      './dot_agent_kernel_dsl_bg.js': wasiShimProxy
+    };
+    
+    try {
+      await WebAssembly.instantiate(wasmBuffer, importObject);
+    } catch (e) {
+      // Expected to fail, but we've captured the function accesses
+      console.log('ℹ️  WASM instantiation attempt complete (may have failed, but functions were captured)');
+    }
+    
+  } catch (err) {
+    console.error('Error during discovery:', err.message);
+    process.exit(1);
+  }
+  
+  // Report findings
+  console.log('\n📊 DISCOVERED FUNCTIONS:\n');
+  
+  const sorted = Array.from(accessedFunctions).sort();
+  
+  console.log(`Total unique functions accessed: ${sorted.length}\n`);
+  
+  // Group by category
+  const groups = {
+    'WASI (fd_*)': [],
+    'WASI (environ_*)': [],
+    'WASI (args_*)': [],
+    'WASI (clock/sched)': [],
+    'UBSAN (__ubsan_*)': [],
+    'wasm-bindgen (__wbg_*)': [],
+    'wasm-bindgen internal (__wbindgen_*)': [],
+    'Other': []
+  };
+  
+  sorted.forEach(fn => {
+    if (fn.startsWith('fd_')) groups['WASI (fd_*)'].push(fn);
+    else if (fn.startsWith('environ_')) groups['WASI (environ_*)'].push(fn);
+    else if (fn.startsWith('args_')) groups['WASI (args_*)'].push(fn);
+    else if (fn.match(/^(clock|sched)/)) groups['WASI (clock/sched)'].push(fn);
+    else if (fn.startsWith('__ubsan_')) groups['UBSAN (__ubsan_*)'].push(fn);
+    else if (fn.startsWith('__wbg_') && !fn.startsWith('__wbindgen_')) groups['wasm-bindgen (__wbg_*)'].push(fn);
+    else if (fn.startsWith('__wbindgen_')) groups['wasm-bindgen internal (__wbindgen_*)'].push(fn);
+    else groups['Other'].push(fn);
+  });
+  
+  Object.entries(groups).forEach(([category, fns]) => {
+    if (fns.length > 0) {
+      console.log(`\n${category}:`);
+      fns.forEach(fn => {
+        const count = functionCallCounts.get(fn);
+        console.log(`  ${fn}: ${count} ${count === 1 ? 'call' : 'calls'}`);
+      });
+    }
+  });
+  
+  // Generate JavaScript code
+  console.log('\n\n📝 GENERATED CODE FOR SHIM:\n');
+  console.log('const wasiShim = {');
+  sorted.forEach(fn => {
+    console.log(`  ${fn}: () => 0,`);
+  });
+  console.log('};');
+}
+
+discoverImports();

package/scripts/patch-wasm-bindgen.js

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const filePath = path.join(__dirname, '../pkg/dot_agent_kernel_dsl.js');
+
+console.log('📝 Patching WASM-bindgen output...');
+
+if (!fs.existsSync(filePath)) {
+  console.warn(`⚠️  File not found: ${filePath}`);
+  process.exit(0);
+}
+
+let content = fs.readFileSync(filePath, 'utf-8');
+
+// Check if already patched
+if (content.includes('MODIFIED: WASM is loaded manually')) {
+  console.log('✅ Already patched');
+  process.exit(0);
+}
+
+// Remove the problematic import lines that cause webpack parse errors
+content = content
+  .replace(/import \* as wasm from ["']\.\/dot_agent_kernel_dsl_bg\.wasm["'];?\n/g, '')
+  .replace(/import { __wbg_set_wasm } from ["']\.\/dot_agent_kernel_dsl_bg\.js["'];?\n/g, '')
+  .replace(/^__wbg_set_wasm\(wasm\);\n/m, '')
+  .replace(/^wasm\.__wbindgen_start\(\);\n/m, '');
+
+// Add comment explaining the change
+if (!content.includes('MODIFIED:')) {
+  content = content.replace(
+    /\/\* @ts-self-types=/,
+    '/* @ts-self-types'
+  );
+  const tsLine = content.match(/\/\* @ts-self-types[^\n]*\n/)[0];
+  content = content.replace(
+    tsLine,
+    tsLine + '/* MODIFIED: WASM is loaded manually by index.js to avoid webpack parse errors */\n'
+  );
+}
+
+fs.writeFileSync(filePath, content, 'utf-8');
+console.log('✅ Patched successfully');