refactor(langgraph): unify agent() return type as LangGraphAgent (#152)

* docs: LangGraph agent() unification design

Eliminate two-step agent()+toAgent() pattern. agent() returns unified
LangGraphAgent (extends AgentWithHistory) preserving all AgentRef
public surface. Type-level tension resolved via langGraph*-prefixed
raw signals (langGraphMessages, langGraphHistory, etc.) alongside
runtime-neutral fields. Breaking change; no compat aliases.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

* docs: LangGraph agent() unification implementation plan

4 tasks: lib refactor (define LangGraphAgent, fold to-agent translation
into agent.fn, delete to-agent.ts, refactor mocks, conformance test),
cockpit migration (~23 demos), website docs migration (~20 files), final
verify + PR. Three commits sequenced to keep each step build-clean.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

* refactor(langgraph): unify agent() return type as LangGraphAgent

Eliminate two-step agent()+toAgent() pattern. agent() now returns
LangGraphAgent extending AgentWithHistory with the full LangGraph-
specific surface preserved (langGraph*-prefixed raw signals where
type collisions exist with the runtime-neutral chat contract).

- Define LangGraphAgent in agent.types.ts
- Fold to-agent translation logic into agent.fn.ts
- Delete to-agent.ts and its specs
- Add agent.conformance.spec.ts (runAgentConformance suite)
- Rename mockAgentRef → mockLangGraphAgent (mock-langgraph-agent.ts)
- public-api.ts: drop toAgent, AgentRef, createMockAgentRef;
  add LangGraphAgent, mockLangGraphAgent

BREAKING: AgentRef is no longer exported. agent() return type changed
from AgentRef to LangGraphAgent. toAgent() removed entirely.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* refactor(cockpit): migrate from agent()+toAgent() to unified LangGraphAgent

25 cockpit angular demos updated. The two field initializers
(stream = agent({...}); chatAgent = toAgent(this.stream)) collapse
to a single field 'agent'. Code reading raw BaseMessage[] switches to
.langGraphMessages(); chat-template bindings now reference the
unified agent.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

* docs(website): align with unified LangGraphAgent API

Update MDX prose, code samples in chat/agent/render docs to reference
LangGraphAgent + the single agent({...}) flow. Regenerate api-docs.json.
Rename createMockAgentRef doc page to mockLangGraphAgent. Update llms.txt
example to single-step.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

* docs(cockpit): update ag-ui streaming prompt to reference Agent contract

* fix(demo): align chat-demo with unified Message type and AgentSubmitInput

- msg.getType() === 'ai' → msg.role === 'assistant' (Message has 'role',
  not BaseMessage's getType()).
- chat.submit({ messages: [{ role: 'human', content }] } as any) →
  chat.submit({ message: content }) (the runtime-neutral
  AgentSubmitInput shape).
- Drop unused BaseMessage import + generic.

This resolves the TS2339 error that blocked website lint/build CI.
The demo's old code path predates the unification refactor and was
reading raw LangChain types directly off the agent.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>

Author: blove

apps/demo/src/app/chat-demo/chat-demo.component.ts

@@ -1,14 +1,13 @@
 import { Component, Input, OnInit, Injector, runInInjectionContext } from '@angular/core';
 import { agent } from '@ngaf/langgraph';
-import type { BaseMessage } from '@langchain/core/messages';
 
 @Component({
   selector: 'stream-chat-demo',
   standalone: false,
   template: `
     <div class="chat-demo">
       <div class="messages" *ngIf="chat">
-        <div *ngFor="let msg of chat.messages()" class="message" [class.ai]="msg.getType() === 'ai'">
+        <div *ngFor="let msg of chat.messages()" class="message" [class.ai]="msg.role === 'assistant'">
           {{ msg.content }}
         </div>
         <div *ngIf="chat.isLoading()" class="loading">Thinking…</div>
@@ -34,14 +33,14 @@ export class ChatDemoComponent implements OnInit {
   @Input() apiUrl = 'http://localhost:2024';
   @Input() assistantId = 'chat_agent';
 
-  chat: ReturnType<typeof agent<{ messages: BaseMessage[] }>> | null = null;
+  chat: ReturnType<typeof agent> | null = null;
 
   constructor(private injector: Injector) {}
 
   ngOnInit() {
     // @Input() values are available in ngOnInit, so use runInInjectionContext
     runInInjectionContext(this.injector, () => {
-      this.chat = agent<{ messages: BaseMessage[] }>({
+      this.chat = agent({
         apiUrl: this.apiUrl,
         assistantId: this.assistantId,
       });
@@ -55,7 +54,6 @@ export class ChatDemoComponent implements OnInit {
     const content = input.value.trim();
     if (!content || !this.chat) return;
     input.value = '';
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    this.chat.submit({ messages: [{ role: 'human', content }] } as any);
+    this.chat.submit({ message: content });
   }
 }

apps/website/content/docs/ag-ui/getting-started/introduction.mdx

@@ -18,7 +18,7 @@ AG-UI is the open agent-to-UI protocol from the CopilotKit ecosystem. It standar
               ┌───────────┴───────────┐
               ▼                       ▼
    @ngaf/langgraph              @ngaf/ag-ui
-   (toAgent: AgentRef→Agent)    (toAgent: AbstractAgent→Agent)
+   (LangGraphAgent)             (toAgent: AbstractAgent→Agent)
               │                       │
               ▼                       ▼
    LangGraph Platform           Any AG-UI backend
@@ -28,7 +28,7 @@ AG-UI is the open agent-to-UI protocol from the CopilotKit ecosystem. It standar
 
 ## What you get
 
-- **`toAgent(source: AbstractAgent): Agent`** — wraps any `AbstractAgent` subclass (custom transports, mocks).
+- **`toAgent(source: AbstractAgent): Agent`** — wraps any `AbstractAgent` subclass (custom transports, mocks) into the runtime-neutral `Agent` contract.
 - **`provideAgUiAgent({ url })`** — DI convenience that instantiates `HttpAgent` under the hood for the common SSE/HTTP case.
 - **`FakeAgent`** — in-process `AbstractAgent` subclass that emits canned streaming events for offline demos and tests.