|
2 | 2 | { |
3 | 3 | "name": "AgentLifecycleRegistry", |
4 | 4 | "kind": "class", |
5 | | - "description": "Optional registry that collects per-instance agent lifecycles within\nan Angular injection context. External instrumentation packages\n(e.g. cockpit-telemetry) provide this token and read from it.\n\n`@threadplane/langgraph` does NOT provide this itself — the configured agent\ninstance writes to the registry only when an external consumer has provided it.", |
| 5 | + "description": "Application-wide registry of every live agent's AgentLifecycle.\n\nIt is `providedIn: 'root'`, so it always exists and every agent registers\ninto the same instance regardless of which injector built it — an agent\ncreated in a route or component injector is still visible from the root.\nExternal instrumentation packages read `lifecycles()` to observe every agent\nin the application without owning the provider graph.\n\nRegistration is scoped to the agent's lifetime: an agent unregisters when the\ninjector that created it is destroyed, so `lifecycles()` never accumulates\nlifecycles for agents that are gone.", |
6 | 6 | "params": [], |
7 | 7 | "examples": [], |
8 | 8 | "properties": [ |
9 | 9 | { |
10 | 10 | "name": "lifecycles", |
11 | 11 | "type": "Signal<readonly AgentLifecycle[]>", |
12 | | - "description": "Reactive list of registered lifecycles.", |
| 12 | + "description": "Reactive list of the lifecycles of every currently live agent.", |
13 | 13 | "optional": false |
14 | 14 | } |
15 | 15 | ], |
|
26 | 26 | "optional": false |
27 | 27 | } |
28 | 28 | ] |
| 29 | + }, |
| 30 | + { |
| 31 | + "name": "unregister", |
| 32 | + "signature": "unregister(lifecycle: AgentLifecycle): void", |
| 33 | + "description": "Drop a lifecycle when its agent's injector is destroyed.", |
| 34 | + "params": [ |
| 35 | + { |
| 36 | + "name": "lifecycle", |
| 37 | + "type": "AgentLifecycle", |
| 38 | + "description": "", |
| 39 | + "optional": false |
| 40 | + } |
| 41 | + ] |
29 | 42 | } |
30 | 43 | ] |
31 | 44 | }, |
|
563 | 576 | { |
564 | 577 | "name": "MockAgentTransport", |
565 | 578 | "kind": "class", |
566 | | - "description": "Test transport for deterministic agent testing without a real LangGraph server.\n\nScript event batches upfront, then emit them manually or step through them\nin your test specs. Supports error injection and close control.", |
| 579 | + "description": "Test transport for deterministic agent testing without a real LangGraph server.\n\nScript event batches upfront, then emit them manually or step through them\nin your test specs. Supports error injection and close control.\n\n`emit()`, `emitError()`, `close()` and `flush()` are awaitable: the returned\npromise settles once the adapter has consumed everything queued so far (and\none macrotask later, so throttled signal writes have landed), which removes\nthe hand-rolled `await new Promise(resolve => setTimeout(resolve, 0))` flush\nfrom specs.", |
567 | 580 | "params": [ |
568 | 581 | { |
569 | 582 | "name": "script", |
|
573 | 586 | } |
574 | 587 | ], |
575 | 588 | "examples": [ |
576 | | - "```typescript\nconst transport = new MockAgentTransport([\n [{ type: 'values', messages: [aiMsg('Hello')] }],\n [{ type: 'values', messages: [aiMsg('Done')] }],\n]);\n```" |
| 589 | + "```typescript\nconst transport = new MockAgentTransport([\n [{ type: 'values', messages: [aiMsg('Hello')] }],\n [{ type: 'values', messages: [aiMsg('Done')] }],\n]);\nawait transport.emit(transport.nextBatch());\n```" |
577 | 590 | ], |
578 | 591 | "properties": [ |
579 | 592 | { |
|
641 | 654 | }, |
642 | 655 | { |
643 | 656 | "name": "close", |
644 | | - "signature": "close(): void", |
645 | | - "description": "Close the stream. Remaining queued events are drained before completion.", |
| 657 | + "signature": "close(): Promise<void>", |
| 658 | + "description": "Close the stream. Remaining queued events are drained before completion.\nResolves once the run has finished.", |
646 | 659 | "params": [] |
647 | 660 | }, |
648 | 661 | { |
|
684 | 697 | }, |
685 | 698 | { |
686 | 699 | "name": "emit", |
687 | | - "signature": "emit(events: StreamEvent[]): void", |
688 | | - "description": "Manually emit events into the stream.", |
| 700 | + "signature": "emit(events: StreamEvent[]): Promise<void>", |
| 701 | + "description": "Manually emit events into the stream.\n\nAwait the returned promise: it resolves once the adapter has pulled this\nbatch out of the stream (or the run has ended), so signals are settled and\nassertions read live state rather than the value from before the emit.", |
689 | 702 | "params": [ |
690 | 703 | { |
691 | 704 | "name": "events", |
|
697 | 710 | }, |
698 | 711 | { |
699 | 712 | "name": "emitError", |
700 | | - "signature": "emitError(err: Error): void", |
701 | | - "description": "Inject an error into the stream.", |
| 713 | + "signature": "emitError(err: Error): Promise<void>", |
| 714 | + "description": "Inject an error into the stream. Resolves once the stream has thrown.", |
702 | 715 | "params": [ |
703 | 716 | { |
704 | 717 | "name": "err", |
|
708 | 721 | } |
709 | 722 | ] |
710 | 723 | }, |
| 724 | + { |
| 725 | + "name": "flush", |
| 726 | + "signature": "flush(): Promise<void>", |
| 727 | + "description": "Resolve once everything emitted so far has been consumed, without emitting\nanything new. Useful after driving the agent by some other route (a\n`submit()`, a `switchThread()`) that has to reach the transport first.", |
| 728 | + "params": [] |
| 729 | + }, |
711 | 730 | { |
712 | 731 | "name": "getHistory", |
713 | 732 | "signature": "getHistory(threadId: string, signal: AbortSignal): Promise<ThreadState<DefaultValues>[]>", |
|
975 | 994 | { |
976 | 995 | "name": "streamErrorAt", |
977 | 996 | "type": "Signal<object | null>", |
978 | | - "description": "Epoch ms + classification of the most recent stream error. Resets on switchThread().", |
| 997 | + "description": "Epoch ms + failure class of the most recent stream error. Resets on switchThread().\n\n`kind` is the AgentErrorKind of the normalized `AgentError`\n(`connection` | `auth` | `server` | `interrupted` | `aborted`) — the same\nvalue `agent.error()?.kind` carries. For a failure the runtime could not\nnormalize it falls back to the error's constructor name.", |
979 | 998 | "optional": false |
980 | 999 | }, |
981 | 1000 | { |
|
1512 | 1531 | { |
1513 | 1532 | "name": "interrupt", |
1514 | 1533 | "type": "Signal<AgentInterrupt | undefined>", |
1515 | | - "description": "", |
1516 | | - "optional": true |
| 1534 | + "description": "Current human-in-the-loop pause, or `undefined` when the run is not paused.\n\nNarrowed from the neutral `Agent` contract, where `interrupt` is optional\nbecause a runtime without human-in-the-loop support omits it. The LangGraph\nadapter always provides it, so `injectAgent().interrupt()` type-checks\ndirectly under `strictNullChecks` — no `?.()` needed.", |
| 1535 | + "optional": false |
1517 | 1536 | }, |
1518 | 1537 | { |
1519 | 1538 | "name": "isLoading", |
|
1946 | 1965 | { |
1947 | 1966 | "name": "interrupt", |
1948 | 1967 | "type": "WritableSignal<AgentInterrupt | undefined>", |
1949 | | - "description": "", |
| 1968 | + "description": "Current human-in-the-loop pause, or `undefined` when the run is not paused.\n\nNarrowed from the neutral `Agent` contract, where `interrupt` is optional\nbecause a runtime without human-in-the-loop support omits it. The LangGraph\nadapter always provides it, so `injectAgent().interrupt()` type-checks\ndirectly under `strictNullChecks` — no `?.()` needed.", |
1950 | 1969 | "optional": false |
1951 | 1970 | }, |
1952 | 1971 | { |
|
2499 | 2518 | { |
2500 | 2519 | "name": "provideAgent", |
2501 | 2520 | "kind": "function", |
2502 | | - "description": "Wire the LangGraph adapter into Angular's dependency injection.\n\nRegisters a singleton `LangGraphAgent` constructed from `config`. Retrieve it\nin any component with `injectAgent()`. Provide this at the application root\n(`app.config.ts`) for an app-wide agent.\n\nTo use a different agent in a component subtree, re-provide\n`provideAgent({...})` in that component's `providers: []` array —\nAngular's hierarchical DI scopes the singleton accordingly.\n\n**Static vs factory config.** Pass a plain `AgentConfig` object when the\nconfig is known up front. Pass a `() => AgentConfig` factory when the config\ndepends on runtime/DI state — the factory runs inside an Angular injection\ncontext, so it may call `inject()` to read services, route params, or\ncomponent-scoped signals.\n\n**Typed state via AgentRef.** Pass a typed ref as the first argument to flow\nthe state shape from `provideAgent` to `injectAgent` without repeating the\ngeneric at every call site.\n\n**Several agents at one injector level.** Each `provideAgent(ref, …)` call\nbuilds its own agent from its own config, so two (or more) refs may be\nprovided side by side in a single `providers` array and `injectAgent(refA)`\n/ `injectAgent(refB)` return distinct agents. The ref-less `injectAgent()`\nresolves a single shared token, which can only point at one of them: when\nmore than one ref is provided at the same level the **last** call wins.\nAlways inject by ref when an injector provides more than one agent.", |
| 2521 | + "description": "Wire the LangGraph adapter into Angular's dependency injection.\n\nRegisters a singleton `LangGraphAgent` constructed from `config`. Retrieve it\nin any component with `injectAgent()`. Provide this at the application root\n(`app.config.ts`) for an app-wide agent.\n\nTo use a different agent in a component subtree, re-provide\n`provideAgent({...})` in that component's `providers: []` array —\nAngular's hierarchical DI scopes the singleton accordingly.\n\n**Static vs factory config.** Pass a plain `AgentConfig` object when the\nconfig is known up front. Pass a `() => AgentConfig` factory when the config\ndepends on runtime/DI state — the factory runs inside an Angular injection\ncontext, so it may call `inject()` to read services, route params, or\ncomponent-scoped signals.\n\n**Typed state via AgentRef.** Pass a typed ref as the first argument to flow\nthe state shape from `provideAgent` to `injectAgent` without repeating the\ngeneric at every call site.\n\n**Several agents at one injector level.** Each `provideAgent(ref, …)` call\nbuilds its own agent from its own config, so two (or more) refs may be\nprovided side by side in a single `providers` array and `injectAgent(refA)`\n/ `injectAgent(refB)` return distinct agents. The ref-less `injectAgent()`\nresolves a single shared token, which can only point at one of them: when\nmore than one ref is provided at the same level the **last** call wins, and\nresolving it in dev mode logs a `console.warn` naming every competing ref.\nThe `AGENT_LIFECYCLE` token follows the same rule. Always inject by ref when\nan injector provides more than one agent.\n\n**Lifecycle token.** Every form also provides `AGENT_LIFECYCLE`, so\n`inject(AGENT_LIFECYCLE)` returns the same object as `injectAgent().lifecycle`\nwithout reaching for the agent itself.", |
2503 | 2522 | "signature": "provideAgent(ref: AgentRef<T>, configOrFactory: AgentConfig<T, BagTemplate> | () => AgentConfig<T>): Provider[]", |
2504 | 2523 | "params": [ |
2505 | 2524 | { |
|
0 commit comments