@dot-agent/language-server 0.2.0

package/AGENTS.md

@@ -0,0 +1,156 @@
+# Agent DSL Language Server — Agent Guidelines
+
+AI collaboration guide for maintaining and evolving the LSP server for `.agent DSL` files.
+
+---
+
+## What this package is
+
+A standalone [Language Server Protocol](https://microsoft.github.io/language-server-protocol/) server that provides all IDE intelligence for the .agent DSL. It speaks LSP over `stdio` and is shared by the VS Code extension, Zed, Neovim, Helix, and any other LSP-capable editor. The server is intentionally editor-agnostic — no VS Code APIs, no Electron, no DOM.
+
+All structural analysis is performed on **tree-sitter ASTs** (not regex). `parser.js` owns the WASM parser lifecycle, document cache, and the helper functions that feature modules use to traverse parse trees.
+
+---
+
+## Module responsibilities
+
+| File | Responsibility |
+|------|---------------|
+| `server.js` | LSP wiring — creates the connection, awaits `initParsers()` in `onInitialize`, registers all `connection.onXxx()` handlers, delegates to `features/` |
+| `parser.js` | Tree-sitter engine — WASM initialization, per-document AST cache, and shared traversal helpers |
+| `features/hover.js` | Hover documentation for all DSL keywords (static lookup, no tree traversal) |
+| `features/completions.js` | Context-aware completions using `getContextNode` and `nodesOfType` for name lookups |
+| `features/diagnostics.js` | Linting — dangling transitions, dead-end interact (AST), deprecated keywords (line scan), undeclared types (AST) |
+| `features/definition.js` | Go-to-definition via `state_decl` / `type_decl` node lookup |
+| `features/references.js` | Find all references via `transition_stmt`, `intent_trigger`, `type_ref` traversal |
+| `features/rename.js` | Rename symbol — same traversal as references, produces `TextEdit[]` |
+| `features/symbols.js` | Document symbol index from `state_decl`, `trigger_decl`, `agent_decl`, `type_decl` nodes |
+| `features/formatting.js` | Indentation normalization (text-based, no tree traversal needed) |
+| `features/links.js` | Document links from `behavior_block`, `schema_prop`, `merge_decl`, `run_stmt` nodes |
+
+**Invariant:** `server.js` contains only LSP wiring. All analysis logic lives in `features/` or `parser.js`.
+
+---
+
+## Adding a new LSP capability
+
+1. Create `features/my-feature.js` exporting a `provideXxx(langId, tree, text, ...)` function.
+2. Import it in `server.js`.
+3. Wire it: `connection.onXxx((params) => { ... return provideXxx(langId, getTree(doc), doc.getText(), ...); })`.
+4. Add the capability to the `capabilities` object in the `initialize` response in `server.js`.
+
+Never put analysis logic directly in `server.js` handlers — always delegate to a feature module.
+
+---
+
+## `parser.js` — tree-sitter API
+
+| Export | Signature | Description |
+|--------|-----------|-------------|
+| `initParsers()` | `async () => void` | Initializes WASM parsers for both grammars. **Must** be awaited in `onInitialize` before any handler runs. |
+| `parse(uri, langId, text, version)` | `→ Tree \| null` | Returns a cached `Tree`, reparsing incrementally when the version changes. Returns `null` if parsers are not yet initialized. |
+| `evict(uri)` | `(uri) → void` | Removes a document's cached tree (call in `onDidClose`). |
+| `nodesOfType(tree, type)` | `→ SyntaxNode[]` | All descendants of the given node type string. |
+| `nodeAtOffset(tree, offset)` | `→ SyntaxNode \| null` | Deepest node at a byte offset. |
+| `nodeToRange(node)` | `→ Range` | Converts a `SyntaxNode` to an LSP `Range` using `startPosition`/`endPosition`. |
+| `positionToOffset(text, line, character)` | `→ number` | Converts an LSP `{line, character}` to a byte offset. |
+| `wordAtPosition(text, line, character)` | `→ {word, start, end}` | Extracts the identifier (including dots) around a cursor position. |
+| `getContextNode(tree, offset)` | `→ SyntaxNode` | Walks up past `ERROR`/`MISSING` nodes to find a clean context ancestor. Use in completions and hover to handle partially-typed input. |
+
+Add shared helpers here — never duplicate tree traversal logic across feature files.
+
+---
+
+## Key node types
+
+### `.behavior` grammar
+
+| Node type | Represents | Useful fields |
+|-----------|-----------|---------------|
+| `state_decl` | `state name block` | `name` (path) |
+| `trigger_decl` | `on event "name" block` | `event` (quoted_string) |
+| `merge_decl` | `merge "file"` | `path` (quoted_string) |
+| `transition_stmt` | `transition to stateName` | `state` (path) |
+| `intent_trigger` | `on intent "text" (transition to state \| block)` | `intent`, `state` (inline only), `block` |
+| `offtopic_stmt` | `on offtopic block` | `block` |
+| `run_stmt` | `run type "target" …` | `run_type`, `target` |
+| `interact_stmt` | `interact [requiring "text"]` | — |
+
+### `.agent` grammar
+
+| Node type | Represents | Useful fields |
+|-----------|-----------|---------------|
+| `agent_decl` | `agent Name …` | `name` (agent_name) |
+| `type_decl` | `type Name …` | `name` (identifier) |
+| `behavior_block` | `behavior file.behavior` | `file` (bare_string) |
+| `schema_prop` | `schema file.json` | `file` (filename) |
+| `type_ref` | `TypeName` or `ns.TypeName` | first named child = identifier |
+| `input_block` / `output_block` / `requires_block` / `capabilities_block` | strict blocks | contain `typed_item`, `type_reference`, `cap_item` |
+
+> **Known limitation:** `on offtopic transition to X` and `on fallback transition to X` in inline form (no block indent) parse as ERROR nodes in the current grammar. Those transitions are not captured by references/rename/diagnostics. Fix requires updating `offtopic_stmt` and `fallback_stmt` in `behavior/grammar.js` to support the inline form.
+
+---
+
+## Dependency constraints
+
+Production dependencies:
+- `vscode-languageserver` and `vscode-languageserver-textdocument` — LSP protocol implementation
+- `web-tree-sitter` — WASM-based tree-sitter runtime
+- `@dot-agent/tree-sitter` — Agent and Flow grammar WASM binaries
+
+Do not add framework dependencies, bundlers, or anything that requires a build step on the language-server side. The server must start with a bare `node server.js --stdio` once the WASM binaries are in `@dot-agent/tree-sitter/dist/`.
+
+The grammar WASM binaries are built by running `npm run build` in the `tree-sitter-agent` package (requires Emscripten). When published to npm, `dist/` is included in the package and no build is needed.
+
+---
+
+## Async lifecycle rule
+
+`web-tree-sitter` initializes asynchronously. The `onInitialize` handler is the only safe place to call `await initParsers()`:
+
+```js
+connection.onInitialize(async () => {
+    await initParsers();   // blocks until both WASMs are loaded
+    return { capabilities: { ... } };
+});
+```
+
+No feature handler will fire before `initialize` completes, so this guarantees parsers are ready before any `onHover`, `onCompletion`, etc. request arrives. Never call `initParsers()` outside `onInitialize`.
+
+---
+
+## License rules
+
+- **Every new `.js` file** must carry the Apache 2.0 header using `/* */` block comment style at the top.
+- No NOTICE file — npm dependencies are not distributed as source.
+
+The Apache 2.0 header:
+```
+/*
+ * 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.
+ */
+```
+
+---
+
+## Key references
+
+| Resource | Link |
+|----------|------|
+| Language specification | [language.md](https://github.com/daniloborges/dot-agent/blob/main/dsl/language.md) |
+| Agent grammar (canonical) | [tree-sitter-agent/grammar.js](https://github.com/daniloborges/tree-sitter-agent/blob/main/grammar.js) |
+| Flow grammar (canonical) | [tree-sitter-agent/flow/grammar.js](https://github.com/daniloborges/tree-sitter-agent/blob/main/flow/grammar.js) |
+| VS Code extension | [vscode-dot-agent](https://github.com/daniloborges/vscode-dot-agent) |
+| WASM execution engine | [dot-agent-kernel](https://github.com/daniloborges/dot-agent-kernel) |

package/LICENSE

@@ -0,0 +1,185 @@
+                                 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 claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by the combination of their Contributions
+      with the Work to which such Contributions were submitted. If You
+      institute patent litigation against any entity (including a cross-claim
+      or counterclaim in a lawsuit) alleging that the Work or any
+      Contribution embodied within the Work constitutes direct or
+      contributory patent infringement, then any 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,186 @@
+# Agent DSL Language Server
+
+A standalone [Language Server Protocol (LSP)](https://microsoft.github.io/language-server-protocol/) server for the **.agent DSL** (`.description`, `.type`, `.behavior`) files. Shared by the VS Code and Zed extensions.
+
+## Features
+
+| Capability | `.agent` | `.behavior` |
+|---|---|---|
+| **Hover** | Keyword documentation | Keyword documentation |
+| **Completion** | Manifest keywords, custom types | Keywords, state names, memory domains (`context.`, `session.`, …) |
+| **Diagnostics** | Deprecated keywords, strict block lint, undeclared types | Dangling `transition` targets, dead-end `interact` |
+| **Go-to-Definition** | Type name → `type` declaration | `transition to stateName` → `state` declaration |
+| **Find References** | All uses of a type | All `transition` references to a state |
+| **Rename** | Type and its references | State and all `transition` references |
+| **Document Symbols** | Agents, types | States, `on event` observers |
+| **Formatting** | 0 / 2-space indentation | 0 / 2 / 4-space indentation by block depth |
+
+> The VS Code extension adds two capabilities on top: **Behavior Graph** (Mermaid state diagram WebView) and **status bar** (current state indicator). Those are VS Code-specific and live in [`extension.js`](https://github.com/daniloborges/vscode-dot-agent/blob/main/extension.js).
+
+## Architecture
+
+```
+┌──────────────┐   LSP/stdio   ┌─────────────────────────────────┐
+│  VS Code     │ ←──────────── │  server.js                      │
+│  Zed         │               │   ├── features/hover.js          │
+│  Neovim/etc  │               │   ├── features/completions.js    │
+└──────────────┘               │   ├── features/diagnostics.js    │
+                               │   ├── features/definition.js     │
+                               │   ├── features/references.js     │
+                               │   ├── features/rename.js         │
+                               │   ├── features/symbols.js        │
+                               │   └── features/formatting.js     │
+                               │   parser.js  (tree-sitter engine)│
+                               └─────────────────────────────────┘
+```
+
+The server speaks LSP over `stdio`. Each editor starts it as a subprocess and communicates via JSON-RPC messages.
+
+All structural analysis uses the **tree-sitter** parse trees from [`@dot-agent/tree-sitter-agent`](https://github.com/daniloborges/tree-sitter-agent). `parser.js` initializes the WASM-based parsers during `initialize` and maintains a per-document AST cache with incremental reparse.
+
+## Prerequisites
+
+The grammar package must have its WASM binaries built before first use:
+
+```bash
+cd dsl/tree-sitter-agent
+npm run build          # requires Emscripten; generates dist/*.wasm
+```
+
+When consuming the package from npm (published), `dist/` is already included — no build step needed.
+
+## Installation
+
+**Standalone (Neovim, Helix, or any LSP-capable editor):**
+
+```bash
+git clone git@github.com:daniloborges/language-server.git
+cd language-server
+# Build the grammar WASMs first (see Prerequisites above)
+npm install
+```
+
+**As a git submodule:**
+
+```bash
+git submodule add git@github.com:daniloborges/language-server.git dsl/language-server
+```
+
+## Usage
+
+Run directly over stdio:
+
+```bash
+node server.js --stdio
+```
+
+### Neovim (nvim-lspconfig)
+
+```lua
+local lspconfig = require('lspconfig')
+local configs = require('lspconfig.configs')
+
+if not configs.agent_dsl then
+  configs.agent_dsl = {
+    default_config = {
+      cmd = { 'node', '/path/to/language-server/server.js', '--stdio' },
+      filetypes = { 'agent', 'behavior' },
+      root_dir = lspconfig.util.root_pattern('.git'),
+    },
+  }
+end
+
+lspconfig.agent_dsl.setup {}
+```
+
+### Helix (`~/.config/helix/languages.toml`)
+
+```toml
+[[language]]
+name = "agent"
+language-servers = ["agent-dsl-lsp"]
+
+[[language]]
+name = "behavior"
+language-servers = ["agent-dsl-lsp"]
+
+[language-server.agent-dsl-lsp]
+command = "node"
+args = ["/path/to/language-server/server.js", "--stdio"]
+```
+
+## VS Code Integration
+
+The [VS Code extension](https://github.com/daniloborges/vscode-dot-agent) installs the server as an npm dependency and starts it automatically via `vscode-languageclient`. No manual setup needed — install the `.vsix` and the server starts with the editor.
+
+## Zed Integration
+
+Configured in `zed-agent/extension.toml` under `[language_servers.agent-dsl-lsp]`. Note: Zed extensions with full LSP support may require Rust bindings depending on the Zed version.
+
+## Development
+
+### Adding a new LSP capability
+
+1. Create `features/my-feature.js` exporting a `provideXxx(langId, tree, text, ...)` function.
+2. Import and wire it in `server.js` via `connection.onXxx(...)`, passing `getTree(doc)` and `doc.getText()`.
+
+### Shared parsing helpers (`parser.js`)
+
+| Export | Description |
+|---|---|
+| `initParsers()` | Async — initializes both WASM parsers. Called once inside `onInitialize`. |
+| `parse(uri, langId, text, version)` | Returns a cached `Tree` for the document, reparsing incrementally on version change. |
+| `evict(uri)` | Removes a document's cached tree on close. |
+| `nodesOfType(tree, type)` | `SyntaxNode[]` — all descendants of the given node type. |
+| `nodeAtOffset(tree, offset)` | The deepest node at a byte offset. |
+| `nodeToRange(node)` | Converts a `SyntaxNode` to an LSP `Range` via `startPosition`/`endPosition`. |
+| `positionToOffset(text, line, character)` | Converts an LSP `{line, character}` to a byte offset. |
+| `wordAtPosition(text, line, character)` | Extracts the identifier (including dots) around a cursor position. |
+| `getContextNode(tree, offset)` | Walks up past `ERROR`/`MISSING` nodes to find a clean context ancestor. |
+
+### Testing features manually
+
+```bash
+# Parse a real file and inspect the AST
+node -e "
+const { initParsers, parse, nodesOfType } = require('./parser');
+(async () => {
+  await initParsers();
+  const text = require('fs').readFileSync('../examples/doctor/doctor.behavior', 'utf8');
+  const tree = parse('f', 'behavior', text, 1);
+  console.log(nodesOfType(tree, 'state_decl').map(n => n.childForFieldName('name').text));
+})();
+"
+
+# Run a diagnostic check
+node -e "
+const { initParsers, parse } = require('./parser');
+const { diagnose } = require('./features/diagnostics');
+(async () => {
+  await initParsers();
+  const text = 'state greeting\n  interact\n  transition to missing\n';
+  const tree = parse('f', 'behavior', text, 1);
+  console.log(diagnose('behavior', tree, text));
+})();
+"
+```
+
+### Testing the full LSP protocol
+
+```bash
+node -e "
+const { spawn } = require('child_process');
+const p = spawn('node', ['server.js', '--stdio']);
+const msg = JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'initialize', params: { processId: null, rootUri: null, capabilities: {} } });
+p.stdin.write('Content-Length: ' + Buffer.byteLength(msg) + '\r\n\r\n' + msg);
+p.stdout.on('data', d => { console.log(d.toString()); p.kill(); });
+"
+```
+
+---
+
+## License
+
+Copyright (c) 2026 Danilo Borges (https://github.com/daniloborges)
+
+Licensed under the **Apache License, Version 2.0** — see [`LICENSE`](LICENSE).

package/features/completions.js

@@ -0,0 +1,112 @@
+/*
+ * 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.
+ */
+
+'use strict';
+
+const { CompletionItemKind } = require('vscode-languageserver');
+const { nodesOfType, positionToOffset, getContextNode } = require('../parser');
+
+const BEHAVIOR_TOP_KW   = ['state', 'merge', 'on event', 'on intent', 'on offtopic', 'on fallback'];
+const BEHAVIOR_BLOCK_KW = ['guide', 'teach', 'goal', 'interact', 'run', 'transition', 'set', 'if', 'else', 'after', 'parallel', 'apply', 'remove', 'on intent', 'on offtopic', 'on fallback', 'on complete', 'on failed'];
+const AGENT_TOP_KW  = ['agent', 'domain', 'license', 'terms', 'privacy', 'description', 'behavior', 'requires', 'input', 'capabilities', 'output', 'type', 'concept', 'schema'];
+const STRICT_BLOCKS = new Set(['input_block', 'output_block', 'requires_block', 'capabilities_block']);
+
+function kw(label) {
+    return { label, kind: CompletionItemKind.Keyword };
+}
+
+// Find the deepest non-error ancestor of a given type
+function nearestAncestor(node, types) {
+    let n = node;
+    while (n) {
+        if (types.includes(n.type)) return n;
+        n = n.parent;
+    }
+    return null;
+}
+
+function provideCompletions(langId, tree, text, position) {
+    const lines = text.split('\n');
+    const line = lines[position.line] || '';
+    const before = line.slice(0, position.character);
+
+    if (langId === 'behavior') {
+        // Keyword-specific completions: use prefix regex (reliable while typing)
+        if (/\btransition\s+to\s+\S*$/.test(before)) {
+            return nodesOfType(tree, 'state_decl')
+                .map(n => n.childForFieldName('name')?.text)
+                .filter(Boolean)
+                .map(name => ({ label: name, kind: CompletionItemKind.Module, detail: 'state' }));
+        }
+        if (/\bset\s+\S*$/.test(before)) {
+            return ['context.', 'session.', 'worksession.', 'user.']
+                .map(d => ({ label: d, kind: CompletionItemKind.Variable, detail: 'memory domain' }));
+        }
+        if (/\brun\s+\S*$/.test(before)) {
+            return ['script', 'subagent', 'tool'].map(kw);
+        }
+        if (/\bon\s+\S*$/.test(before)) {
+            return ['event', 'intent', 'offtopic', 'fallback', 'complete', 'failed'].map(kw);
+        }
+
+        // Context-aware: top-level vs. inside a block
+        if (tree) {
+            const offset = positionToOffset(text, position.line, position.character);
+            const ctx = getContextNode(tree, offset);
+            const inBlock = !!nearestAncestor(ctx, ['block']);
+            return (inBlock ? BEHAVIOR_BLOCK_KW : BEHAVIOR_TOP_KW).map(kw);
+        }
+        return (/^\s/.test(line) ? BEHAVIOR_BLOCK_KW : BEHAVIOR_TOP_KW).map(kw);
+    }
+
+    if (langId === 'agent') {
+        if (!/^\s/.test(line)) {
+            return AGENT_TOP_KW.map(kw);
+        }
+
+        // Inside a strict block → suggest declared types
+        if (tree) {
+            const offset = positionToOffset(text, position.line, position.character);
+            const ctx = getContextNode(tree, offset);
+            const strictBlock = nearestAncestor(ctx, [...STRICT_BLOCKS]);
+            if (strictBlock) {
+                return nodesOfType(tree, 'type_decl')
+                    .map(n => n.childForFieldName('name')?.text)
+                    .filter(Boolean)
+                    .map(name => ({ label: name, kind: CompletionItemKind.Class, detail: 'type' }));
+            }
+        } else {
+            // Fallback: text-based block detection
+            for (let i = position.line - 1; i >= 0; i--) {
+                const prev = lines[i];
+                if (/^\s/.test(prev)) continue;
+                const blockKw = (prev.trim().split(/\s+/)[0] || '');
+                if (['input', 'output', 'requires', 'capabilities'].includes(blockKw)) {
+                    return nodesOfType(tree, 'type_decl')
+                        .map(n => n.childForFieldName('name')?.text)
+                        .filter(Boolean)
+                        .map(name => ({ label: name, kind: CompletionItemKind.Class, detail: 'type' }));
+                }
+                break;
+            }
+        }
+        return [];
+    }
+
+    return [];
+}
+
+module.exports = { provideCompletions };