@moldea.ai/adapter-langchain 3.0.1 → 3.0.3

package/README.md

@@ -19,7 +19,7 @@ const core = createCore({ adapters: [langChainAdapter] });
 
 ## Verified target
 
-Version `3.0.1` supports Repository Format `1`, `@moldea.ai/core ^4.0.0`, and declared ranges that intersect `langchain >=1.5.9` with companion `@langchain/core >=1.2.8`. Those minimum versions are verified. Later stable releases are eligible for deterministic inspection on a best-effort basis and must still match the documented source patterns. Qualification evidence records the exact package versions and date used for each execution. The target recognizes:
+Version `3.0.3` supports Repository Format `1`, `@moldea.ai/core ^4.0.0`, and declared ranges that intersect `langchain >=1.5.9` with companion `@langchain/core >=1.2.8`. Those minimum versions are verified. Later stable releases are eligible for deterministic inspection on a best-effort basis and must still match the documented source patterns. Qualification evidence records the exact package versions and date used for each execution. The target recognizes:
 
 - directly exported package-root `createAgent(...)` definitions
 - direct instruction-loader calls and `SystemMessage` construction
@@ -35,6 +35,10 @@ The package exports only `langChainAdapter`. It has no default export, configura
 
 ## Documentation
 
+- [Complete binding example](docs/binding-example.md): manifest, canonical instructions, runtime source, and supported schema or routing relationships.
+
+These guides are included in the installed package. Open only the page relevant to your task.
+
 - [Package overview](docs/index.md)
 - [Verified target](docs/verified-target.md)
 - [Evidence and diagnostics](docs/evidence-and-diagnostics.md)

package/docs/binding-example.md

@@ -0,0 +1,155 @@
+---
+title: Binding example
+description: Complete manifest and source files for inspecting langchain bindings locally.
+order: 5
+---
+
+# Binding example
+
+Read this example before searching adapter implementation for binding syntax. It is a complete **static inspection** file set, not a deployment starter or a live provider test. The files are checked together through this adapter and Core without installing or executing the target SDK. Keep application setup, credentials, provider model access, tool execution, and deployment configuration separate.
+
+## How the bindings connect
+
+Bind the exported `createAgent` result. `systemPrompt` calls the canonical loader, `responseFormat` uses the bound agent output schema, and each tool has a distinct implementation, registration, and input schema. The example uses no middleware: unknown middleware can leave relationships unresolved. This target does not establish handoff, agent input-schema, or tool output-schema evidence.
+
+Paths below are repository-root-relative logical paths. Keep the canonical instructions as the policy source. General manifest semantics belong to the [Repository Format specification](https://packages.moldea.ai/repository-format/). Use the other local guides for the full supported boundary and limitations; this example does not expand them.
+
+## Files
+
+<!-- example:start -->
+
+### /moldea/moldea.yaml
+
+```yaml
+version: 1
+agents:
+  support:
+    runtime:
+      id: 'langchain'
+    bindings:
+      runtimeAgent:
+        path: '/src/agent.ts'
+        symbol: 'supportAgent'
+      instructionLoader:
+        path: '/src/instructions.ts'
+        symbol: 'loadSupportInstruction'
+      outputSchema:
+        path: '/src/contracts.ts'
+        symbol: 'SupportOutputSchema'
+    tools:
+      find-order:
+        name: 'find_order'
+        description: 'Finds an order.'
+        implementation:
+          path: '/src/implementations.ts'
+          symbol: 'findOrder'
+        registration:
+          path: '/src/tools.ts'
+          symbol: 'findOrderTool'
+        inputSchema:
+          path: '/src/contracts.ts'
+          symbol: 'FindOrderInputSchema'
+```
+
+### /package.json
+
+```json
+{
+  "dependencies": {
+    "@langchain/core": "~1.2.8",
+    "langchain": "~1.5.9",
+    "zod": "4.6.4"
+  },
+  "name": "binding-example",
+  "private": true,
+  "type": "module"
+}
+```
+
+### /moldea/project.md
+
+```markdown
+# Fixture project
+```
+
+### /moldea/agents/support/description.md
+
+```markdown
+Supports customers.
+```
+
+### /moldea/agents/support/instruction.md
+
+```markdown
+You are the `support` agent.
+
+Answer from supplied support facts. Do not invent order status or account information.
+```
+
+### /src/contracts.ts
+
+```typescript
+import { z } from 'zod';
+
+// response and tool contracts
+export const SupportOutputSchema = z.object({ summary: z.string() });
+export const FindOrderInputSchema = z.object({ orderId: z.string() });
+```
+
+### /src/instructions.ts
+
+```typescript
+import { readFileSync } from 'node:fs';
+
+/** Reads the canonical support instruction. */
+export const loadSupportInstruction = (): string =>
+  readFileSync(new URL('../moldea/agents/support/instruction.md', import.meta.url), 'utf8');
+```
+
+### /src/implementations.ts
+
+```typescript
+/** Looks up an order in the example's fixed catalog. */
+export const findOrder = async ({ orderId }: { orderId: string }) => ({
+  orderId,
+  status: orderId === 'order-1042' ? ('shipped' as const) : ('not_found' as const),
+});
+```
+
+### /src/tools.ts
+
+```typescript
+import { tool } from '@langchain/core/tools';
+import { FindOrderInputSchema } from './contracts.js';
+import { findOrder } from './implementations.js';
+export const findOrderTool = tool(findOrder, {
+  name: 'find_order',
+  description: 'Finds an order.',
+  schema: FindOrderInputSchema,
+});
+```
+
+### /src/agent.ts
+
+```typescript
+import { createAgent, providerStrategy, SystemMessage } from 'langchain';
+import { SupportOutputSchema } from './contracts.js';
+import { loadSupportInstruction } from './instructions.js';
+import { findOrderTool } from './tools.js';
+const MIDDLEWARE = [];
+const TOOLS = [findOrderTool];
+export const supportAgent = createAgent({
+  model: 'openai:gpt-4o',
+  name: 'support-runtime',
+  systemPrompt: new SystemMessage(loadSupportInstruction()),
+  responseFormat: providerStrategy({ schema: SupportOutputSchema, strict: true }),
+  middleware: MIDDLEWARE,
+  tools: TOOLS,
+});
+```
+
+<!-- example:end -->
+
+## What the check establishes
+
+The integration check reads these exact file blocks, requires positive adapter evidence for the documented relationships, and rejects a broken runtime binding. It does not prove that instructions are followed, that every SDK version accepts these forms, or that the application is ready for production. Continue using the installed adapter diagnostics for your actual source.

package/docs/evidence-and-diagnostics.md

@@ -0,0 +1,32 @@
+---
+title: Evidence and diagnostics
+description: Source-grounded LangChain observations and stable adapter failures.
+order: 20
+---
+
+# Evidence and diagnostics
+
+The adapter may emit `runtime-package`, `language`, `agent-definition`, `instruction-loader`, `schema`, and `tool-registration` evidence. Dynamic, middleware-influenced, multi-schema, or otherwise unresolved forms suppress optimistic evidence and contradiction diagnostics that would require guessing runtime behavior.
+
+## Stable diagnostics
+
+| Code                                             | Message                                                                                                  |
+| ------------------------------------------------ | -------------------------------------------------------------------------------------------------------- |
+| `LANGCHAIN_PACKAGE_MANIFEST_INVALID`             | The owning package manifest is invalid for LangChain dependency detection.                               |
+| `LANGCHAIN_VERSION_UNSUPPORTED`                  | The observed LangChain package ranges are disjoint from the supported target.                            |
+| `LANGCHAIN_SOURCE_TEXT_INVALID`                  | The referenced LangChain source file is not valid normalized text.                                       |
+| `LANGCHAIN_SOURCE_SYNTAX_INVALID`                | The referenced LangChain source file contains invalid TypeScript syntax.                                 |
+| `LANGCHAIN_RUNTIME_AGENT_SYMBOL_NOT_FOUND`       | The declared runtime-agent symbol was not found.                                                         |
+| `LANGCHAIN_INSTRUCTION_LOADER_SYMBOL_NOT_FOUND`  | The declared instruction-loader symbol was not found.                                                    |
+| `LANGCHAIN_AGENT_OUTPUT_SCHEMA_SYMBOL_NOT_FOUND` | The declared agent output-schema symbol was not found.                                                   |
+| `LANGCHAIN_TOOL_IMPLEMENTATION_SYMBOL_NOT_FOUND` | The declared tool-implementation symbol was not found.                                                   |
+| `LANGCHAIN_TOOL_REGISTRATION_SYMBOL_NOT_FOUND`   | The declared tool-registration symbol was not found.                                                     |
+| `LANGCHAIN_TOOL_INPUT_SCHEMA_SYMBOL_NOT_FOUND`   | The declared tool input-schema symbol was not found.                                                     |
+| `LANGCHAIN_INSTRUCTION_LOADER_NOT_WIRED`         | The declared instruction loader is not wired to the detected LangChain agent.                            |
+| `LANGCHAIN_AGENT_OUTPUT_SCHEMA_NOT_WIRED`        | The declared agent output schema is not wired to the detected LangChain structured-output configuration. |
+| `LANGCHAIN_TOOL_IMPLEMENTATION_NOT_WIRED`        | The declared tool implementation is not wired to the detected LangChain function tool.                   |
+| `LANGCHAIN_TOOL_REGISTRATION_NOT_WIRED`          | The declared tool registration is not available to the detected LangChain agent.                         |
+| `LANGCHAIN_TOOL_NAME_MISMATCH`                   | The declared tool name does not match the detected LangChain tool name.                                  |
+| `LANGCHAIN_TOOL_INPUT_SCHEMA_NOT_WIRED`          | The declared tool input schema is not wired to the detected LangChain function tool.                     |
+
+Diagnostics never include source snippets, descriptions, instructions, schema contents, credentials, URLs, host paths, package declarations that are not valid SemVer ranges, or raw TypeScript diagnostic messages.

package/docs/index.md

@@ -0,0 +1,15 @@
+---
+title: LangChain adapter
+description: Deterministic evidence for LangChain TypeScript createAgent applications.
+order: 1
+---
+
+# LangChain adapter
+
+`@moldea.ai/adapter-langchain` connects Repository Format `1` declarations to static LangChain `createAgent` forms. `langchain` `1.5.9` and companion `@langchain/core` `1.2.8` are the verified minimums. Later stable releases are eligible for deterministic inspection on a best-effort basis and must still match the documented source patterns.
+
+The adapter begins at each declared runtime-agent path, finds its nearest owning package, checks the primary and companion declarations together, and returns immutable evidence and stable diagnostics through Core. It does not execute the application or treat package presence as proof of an agent definition.
+
+The package exports only `langChainAdapter`. The generated API reference derives that surface from the package export.
+
+Start with the [complete binding example](https://packages.moldea.ai/adapters/langchain/binding-example/) when connecting runtime source to canonical instructions, schemas, tools, or routing metadata. The same example ships locally as `docs/binding-example.md` in the installed package.

package/docs/limitations.md

@@ -0,0 +1,15 @@
+---
+title: Limitations
+description: Conservative boundaries of the initial LangChain adapter target.
+order: 30
+---
+
+# Limitations
+
+The initial target intentionally excludes JavaScript and CommonJS, configuration objects passed by reference, wrapper factories, re-exports, path aliases, package barrels, legacy agent executors, direct LangGraph graphs, Deep Agents, supervisor libraries, headless tools, custom tool classes, provider and server tools, toolkits, MCP conversions, and dynamic tool collections.
+
+Non-empty or unresolved middleware suppresses instruction, agent output-schema, and tool-registration conclusions. Developer-authored response-format arrays are not mapped to the Repository Format's single agent output-schema binding. `stateSchema` and `contextSchema` do not become agent input-schema evidence, and implementation return types do not become tool output-schema evidence.
+
+The adapter does not validate model availability, provider compatibility, schema semantics, tool safety, prompt quality, routing intent, or runtime execution. Direct LangGraph applications remain the responsibility of the separate `langgraph` runtime boundary.
+
+Each invocation sees one declared agent and bounded logical repository operations, not a complete agent collection or project body index.

package/docs/verified-target.md

@@ -0,0 +1,15 @@
+---
+title: Verified target
+description: Static forms covered by the LangChain createAgent target from its verified minimums.
+order: 10
+---
+
+# Verified target
+
+Technical target `typescript-create-agent-1-5` admits declared ranges that intersect `langchain >=1.5.9` with companion `@langchain/core >=1.2.8`. Those minimum versions are verified. Later stable releases are eligible for deterministic inspection on a best-effort basis and must still match the source patterns below. Qualification evidence records the exact package versions and date used for each execution.
+
+Positive agent evidence requires a directly exported TypeScript `const` initialized by the named package-root `createAgent(...)` helper with one closed object-literal configuration and a `model` property. Named import aliases and `.ts`, `.tsx`, and `.mts` source are supported.
+
+Instruction relationships require a direct loader call in `systemPrompt` or a direct `SystemMessage(loaderCall)` construction. Agent output schemas may be direct or wrapped by a supported one-schema `toolStrategy(...)` or `providerStrategy(...)` call. Normal function tools require the two-argument `tool(implementation, fields)` overload and an explicit manifest registration binding. Agent registration requires a closed tool array.
+
+Middleware must be absent or a provably immutable empty array before instruction, agent output-schema, or tool-registration conclusions are produced. The adapter itself supports Node.js `>=22.11.0`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moldea.ai/adapter-langchain",
-  "version": "3.0.1",
+  "version": "3.0.3",
   "description": "Deterministic runtime evidence and diagnostics for LangChain TypeScript agents.",
   "homepage": "https://github.com/moldea-ai/packages/tree/main/projects/adapter-langchain#readme",
   "bugs": {
@@ -18,6 +18,7 @@
   "files": [
     "cover.png",
     "dist",
+    "docs",
     "LICENSE",
     "README.md"
   ],