@a2a-wrapper/core 1.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (50) hide show
  1. package/README.md +186 -0
  2. package/dist/cli/scaffold.d.ts +237 -0
  3. package/dist/cli/scaffold.d.ts.map +1 -0
  4. package/dist/cli/scaffold.js +241 -0
  5. package/dist/cli/scaffold.js.map +1 -0
  6. package/dist/config/loader.d.ts +100 -0
  7. package/dist/config/loader.d.ts.map +1 -0
  8. package/dist/config/loader.js +130 -0
  9. package/dist/config/loader.js.map +1 -0
  10. package/dist/config/types.d.ts +317 -0
  11. package/dist/config/types.d.ts.map +1 -0
  12. package/dist/config/types.js +17 -0
  13. package/dist/config/types.js.map +1 -0
  14. package/dist/events/event-publisher.d.ts +205 -0
  15. package/dist/events/event-publisher.d.ts.map +1 -0
  16. package/dist/events/event-publisher.js +317 -0
  17. package/dist/events/event-publisher.js.map +1 -0
  18. package/dist/executor/types.d.ts +164 -0
  19. package/dist/executor/types.d.ts.map +1 -0
  20. package/dist/executor/types.js +30 -0
  21. package/dist/executor/types.js.map +1 -0
  22. package/dist/index.d.ts +37 -0
  23. package/dist/index.d.ts.map +1 -0
  24. package/dist/index.js +34 -0
  25. package/dist/index.js.map +1 -0
  26. package/dist/server/agent-card.d.ts +66 -0
  27. package/dist/server/agent-card.d.ts.map +1 -0
  28. package/dist/server/agent-card.js +114 -0
  29. package/dist/server/agent-card.js.map +1 -0
  30. package/dist/server/factory.d.ts +159 -0
  31. package/dist/server/factory.d.ts.map +1 -0
  32. package/dist/server/factory.js +167 -0
  33. package/dist/server/factory.js.map +1 -0
  34. package/dist/session/base-session-manager.d.ts +218 -0
  35. package/dist/session/base-session-manager.d.ts.map +1 -0
  36. package/dist/session/base-session-manager.js +222 -0
  37. package/dist/session/base-session-manager.js.map +1 -0
  38. package/dist/utils/deep-merge.d.ts +83 -0
  39. package/dist/utils/deep-merge.d.ts.map +1 -0
  40. package/dist/utils/deep-merge.js +108 -0
  41. package/dist/utils/deep-merge.js.map +1 -0
  42. package/dist/utils/deferred.d.ts +97 -0
  43. package/dist/utils/deferred.d.ts.map +1 -0
  44. package/dist/utils/deferred.js +83 -0
  45. package/dist/utils/deferred.js.map +1 -0
  46. package/dist/utils/logger.d.ts +186 -0
  47. package/dist/utils/logger.d.ts.map +1 -0
  48. package/dist/utils/logger.js +244 -0
  49. package/dist/utils/logger.js.map +1 -0
  50. package/package.json +57 -0
@@ -0,0 +1,100 @@
1
+ /**
2
+ * Configuration Loader
3
+ *
4
+ * Provides a generic, layered configuration loading pipeline for A2A agent
5
+ * wrapper projects. Configuration is resolved by merging four layers in
6
+ * ascending priority order:
7
+ *
8
+ * **defaults ← JSON config file ← environment overrides ← CLI overrides**
9
+ *
10
+ * Each layer is deep-merged using {@link deepMerge} from the utils module,
11
+ * ensuring that nested objects are recursively merged while arrays are
12
+ * replaced and `undefined` values are skipped.
13
+ *
14
+ * This module is intentionally backend-agnostic. It does **not** include
15
+ * `loadEnvOverrides` or `substituteEnvTokensInMcpArgs` — those are
16
+ * wrapper-specific concerns that each project implements independently.
17
+ *
18
+ * @module config/loader
19
+ */
20
+ import type { BaseAgentConfig } from "./types.js";
21
+ /**
22
+ * Read and parse a JSON configuration file from disk.
23
+ *
24
+ * The provided `filePath` is resolved to an absolute path before reading.
25
+ * If the file cannot be read or its contents are not valid JSON, a
26
+ * descriptive `Error` is thrown that includes the absolute file path and
27
+ * the underlying error message — making it straightforward to diagnose
28
+ * deployment-time configuration issues.
29
+ *
30
+ * @typeParam T - The expected shape of the parsed configuration object.
31
+ * No runtime validation is performed; the caller is responsible for
32
+ * ensuring the file contents match `T`.
33
+ *
34
+ * @param filePath - Relative or absolute path to the JSON configuration
35
+ * file. Resolved against `process.cwd()` when relative.
36
+ * @returns The parsed configuration object cast to `T`.
37
+ *
38
+ * @throws {Error} When the file cannot be read (e.g. missing, permission
39
+ * denied) or when the contents are not valid JSON. The error message
40
+ * includes the absolute file path and the underlying cause.
41
+ *
42
+ * @example
43
+ * ```typescript
44
+ * interface MyConfig { port: number; host: string }
45
+ * const config = loadConfigFile<MyConfig>("./config.json");
46
+ * // config.port, config.host are available
47
+ * ```
48
+ */
49
+ export declare function loadConfigFile<T>(filePath: string): T;
50
+ /**
51
+ * Build the final resolved configuration by merging four layers in
52
+ * ascending priority order:
53
+ *
54
+ * **defaults ← config file ← environment overrides ← CLI overrides**
55
+ *
56
+ * Each layer is deep-merged using {@link deepMerge}, which recursively
57
+ * merges nested objects, replaces arrays, skips `undefined` values, and
58
+ * allows `null` to explicitly clear a field.
59
+ *
60
+ * The function is generic over `T` (which must extend
61
+ * {@link BaseAgentConfig}), so each wrapper project can pass its own full
62
+ * config type through the pipeline and receive a fully typed result.
63
+ *
64
+ * @typeParam T - The full configuration type for the wrapper project.
65
+ * Must extend `BaseAgentConfig<unknown>` to ensure the standard shared
66
+ * sections (agentCard, server, session, etc.) are present.
67
+ *
68
+ * @param defaults - The complete default configuration object. This serves
69
+ * as the base layer and should have every field populated so that the
70
+ * returned config is guaranteed to be fully resolved.
71
+ * @param configFilePath - Optional path to a JSON configuration file. When
72
+ * provided, the file is loaded via {@link loadConfigFile} and merged on
73
+ * top of `defaults`.
74
+ * @param envOverrides - Optional partial configuration derived from
75
+ * environment variables. Merged on top of the file layer.
76
+ * @param cliOverrides - Optional partial configuration derived from CLI
77
+ * arguments. Merged last, giving CLI flags the highest precedence.
78
+ * @returns The fully resolved configuration with all fields populated.
79
+ *
80
+ * @throws {Error} If `configFilePath` is provided but the file cannot be
81
+ * read or parsed (propagated from {@link loadConfigFile}).
82
+ *
83
+ * @example
84
+ * ```typescript
85
+ * import type { BaseAgentConfig } from "./types.js";
86
+ *
87
+ * interface MyBackend { apiKey: string }
88
+ * type MyConfig = BaseAgentConfig<MyBackend>;
89
+ *
90
+ * const resolved = resolveConfig<MyConfig>(
91
+ * MY_DEFAULTS,
92
+ * "./config.json",
93
+ * envOverrides,
94
+ * cliOverrides,
95
+ * );
96
+ * // resolved.server.port, resolved.backend.apiKey, etc.
97
+ * ```
98
+ */
99
+ export declare function resolveConfig<T extends BaseAgentConfig<unknown>>(defaults: Required<T>, configFilePath?: string, envOverrides?: Partial<T>, cliOverrides?: Partial<T>): Required<T>;
100
+ //# sourceMappingURL=loader.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../../src/config/loader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAMH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAIlD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,GAAG,CAAC,CASrD;AAID;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS,eAAe,CAAC,OAAO,CAAC,EAC9D,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC,EACrB,cAAc,CAAC,EAAE,MAAM,EACvB,YAAY,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC,EACzB,YAAY,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC,GACxB,QAAQ,CAAC,CAAC,CAAC,CAuBb"}
@@ -0,0 +1,130 @@
1
+ /**
2
+ * Configuration Loader
3
+ *
4
+ * Provides a generic, layered configuration loading pipeline for A2A agent
5
+ * wrapper projects. Configuration is resolved by merging four layers in
6
+ * ascending priority order:
7
+ *
8
+ * **defaults ← JSON config file ← environment overrides ← CLI overrides**
9
+ *
10
+ * Each layer is deep-merged using {@link deepMerge} from the utils module,
11
+ * ensuring that nested objects are recursively merged while arrays are
12
+ * replaced and `undefined` values are skipped.
13
+ *
14
+ * This module is intentionally backend-agnostic. It does **not** include
15
+ * `loadEnvOverrides` or `substituteEnvTokensInMcpArgs` — those are
16
+ * wrapper-specific concerns that each project implements independently.
17
+ *
18
+ * @module config/loader
19
+ */
20
+ import { readFileSync } from "node:fs";
21
+ import { resolve } from "node:path";
22
+ import { deepMerge } from "../utils/deep-merge.js";
23
+ // ─── JSON File Loader ───────────────────────────────────────────────────────
24
+ /**
25
+ * Read and parse a JSON configuration file from disk.
26
+ *
27
+ * The provided `filePath` is resolved to an absolute path before reading.
28
+ * If the file cannot be read or its contents are not valid JSON, a
29
+ * descriptive `Error` is thrown that includes the absolute file path and
30
+ * the underlying error message — making it straightforward to diagnose
31
+ * deployment-time configuration issues.
32
+ *
33
+ * @typeParam T - The expected shape of the parsed configuration object.
34
+ * No runtime validation is performed; the caller is responsible for
35
+ * ensuring the file contents match `T`.
36
+ *
37
+ * @param filePath - Relative or absolute path to the JSON configuration
38
+ * file. Resolved against `process.cwd()` when relative.
39
+ * @returns The parsed configuration object cast to `T`.
40
+ *
41
+ * @throws {Error} When the file cannot be read (e.g. missing, permission
42
+ * denied) or when the contents are not valid JSON. The error message
43
+ * includes the absolute file path and the underlying cause.
44
+ *
45
+ * @example
46
+ * ```typescript
47
+ * interface MyConfig { port: number; host: string }
48
+ * const config = loadConfigFile<MyConfig>("./config.json");
49
+ * // config.port, config.host are available
50
+ * ```
51
+ */
52
+ export function loadConfigFile(filePath) {
53
+ const absPath = resolve(filePath);
54
+ try {
55
+ const raw = readFileSync(absPath, "utf-8");
56
+ return JSON.parse(raw);
57
+ }
58
+ catch (err) {
59
+ const msg = err instanceof Error ? err.message : String(err);
60
+ throw new Error(`Failed to load config file "${absPath}": ${msg}`);
61
+ }
62
+ }
63
+ // ─── Merge Pipeline ─────────────────────────────────────────────────────────
64
+ /**
65
+ * Build the final resolved configuration by merging four layers in
66
+ * ascending priority order:
67
+ *
68
+ * **defaults ← config file ← environment overrides ← CLI overrides**
69
+ *
70
+ * Each layer is deep-merged using {@link deepMerge}, which recursively
71
+ * merges nested objects, replaces arrays, skips `undefined` values, and
72
+ * allows `null` to explicitly clear a field.
73
+ *
74
+ * The function is generic over `T` (which must extend
75
+ * {@link BaseAgentConfig}), so each wrapper project can pass its own full
76
+ * config type through the pipeline and receive a fully typed result.
77
+ *
78
+ * @typeParam T - The full configuration type for the wrapper project.
79
+ * Must extend `BaseAgentConfig<unknown>` to ensure the standard shared
80
+ * sections (agentCard, server, session, etc.) are present.
81
+ *
82
+ * @param defaults - The complete default configuration object. This serves
83
+ * as the base layer and should have every field populated so that the
84
+ * returned config is guaranteed to be fully resolved.
85
+ * @param configFilePath - Optional path to a JSON configuration file. When
86
+ * provided, the file is loaded via {@link loadConfigFile} and merged on
87
+ * top of `defaults`.
88
+ * @param envOverrides - Optional partial configuration derived from
89
+ * environment variables. Merged on top of the file layer.
90
+ * @param cliOverrides - Optional partial configuration derived from CLI
91
+ * arguments. Merged last, giving CLI flags the highest precedence.
92
+ * @returns The fully resolved configuration with all fields populated.
93
+ *
94
+ * @throws {Error} If `configFilePath` is provided but the file cannot be
95
+ * read or parsed (propagated from {@link loadConfigFile}).
96
+ *
97
+ * @example
98
+ * ```typescript
99
+ * import type { BaseAgentConfig } from "./types.js";
100
+ *
101
+ * interface MyBackend { apiKey: string }
102
+ * type MyConfig = BaseAgentConfig<MyBackend>;
103
+ *
104
+ * const resolved = resolveConfig<MyConfig>(
105
+ * MY_DEFAULTS,
106
+ * "./config.json",
107
+ * envOverrides,
108
+ * cliOverrides,
109
+ * );
110
+ * // resolved.server.port, resolved.backend.apiKey, etc.
111
+ * ```
112
+ */
113
+ export function resolveConfig(defaults, configFilePath, envOverrides, cliOverrides) {
114
+ let merged = deepMerge({}, defaults);
115
+ // Layer 1: JSON config file
116
+ if (configFilePath) {
117
+ const fileConfig = loadConfigFile(configFilePath);
118
+ merged = deepMerge(merged, fileConfig);
119
+ }
120
+ // Layer 2: Environment variable overrides
121
+ if (envOverrides) {
122
+ merged = deepMerge(merged, envOverrides);
123
+ }
124
+ // Layer 3: CLI argument overrides (highest precedence)
125
+ if (cliOverrides) {
126
+ merged = deepMerge(merged, cliOverrides);
127
+ }
128
+ return merged;
129
+ }
130
+ //# sourceMappingURL=loader.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"loader.js","sourceRoot":"","sources":["../../src/config/loader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAGnD,+EAA+E;AAE/E;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,UAAU,cAAc,CAAI,QAAgB;IAChD,MAAM,OAAO,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IAClC,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,YAAY,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QAC3C,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAM,CAAC;IAC9B,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,GAAG,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAC7D,MAAM,IAAI,KAAK,CAAC,+BAA+B,OAAO,MAAM,GAAG,EAAE,CAAC,CAAC;IACrE,CAAC;AACH,CAAC;AAED,+EAA+E;AAE/E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH,MAAM,UAAU,aAAa,CAC3B,QAAqB,EACrB,cAAuB,EACvB,YAAyB,EACzB,YAAyB;IAEzB,IAAI,MAAM,GAAG,SAAS,CACpB,EAA6B,EAC7B,QAA8C,CAC/C,CAAC;IAEF,4BAA4B;IAC5B,IAAI,cAAc,EAAE,CAAC;QACnB,MAAM,UAAU,GAAG,cAAc,CAAI,cAAc,CAAC,CAAC;QACrD,MAAM,GAAG,SAAS,CAAC,MAAM,EAAE,UAAgD,CAAC,CAAC;IAC/E,CAAC;IAED,0CAA0C;IAC1C,IAAI,YAAY,EAAE,CAAC;QACjB,MAAM,GAAG,SAAS,CAAC,MAAM,EAAE,YAAkD,CAAC,CAAC;IACjF,CAAC;IAED,uDAAuD;IACvD,IAAI,YAAY,EAAE,CAAC;QACjB,MAAM,GAAG,SAAS,CAAC,MAAM,EAAE,YAAkD,CAAC,CAAC;IACjF,CAAC;IAED,OAAO,MAAgC,CAAC;AAC1C,CAAC"}
@@ -0,0 +1,317 @@
1
+ /**
2
+ * Base Configuration Types
3
+ *
4
+ * Shared TypeScript interfaces for all configurable aspects of an A2A agent
5
+ * wrapper deployment. These types unify the common configuration sections
6
+ * found in both `a2a-copilot` and `a2a-opencode`, providing a single source
7
+ * of truth for agent card identity, server networking, session lifecycle,
8
+ * feature flags, timeouts, logging, and MCP server definitions.
9
+ *
10
+ * Wrapper-specific configuration (e.g. `CopilotConfig`, `OpenCodeConfig`) is
11
+ * injected via the `TBackend` generic parameter on {@link BaseAgentConfig},
12
+ * keeping this module completely decoupled from any particular backend.
13
+ *
14
+ * @module config/types
15
+ */
16
+ /**
17
+ * A single skill exposed on the agent card.
18
+ *
19
+ * Skills describe discrete capabilities the agent advertises to orchestrators
20
+ * and callers via the A2A Agent Card. Each skill has a unique identifier,
21
+ * human-readable metadata, and optional usage examples.
22
+ */
23
+ export interface SkillConfig {
24
+ /**
25
+ * Unique identifier for this skill.
26
+ * Used as the stable key when referencing the skill programmatically.
27
+ */
28
+ id: string;
29
+ /**
30
+ * Human-readable display name for the skill.
31
+ * Shown in agent card UIs and orchestrator dashboards.
32
+ */
33
+ name: string;
34
+ /**
35
+ * Detailed description of what this skill does.
36
+ * Helps orchestrators decide whether to route a task to this agent.
37
+ */
38
+ description: string;
39
+ /**
40
+ * Optional tags for categorization and discovery.
41
+ * Orchestrators may use tags to filter or group agents by capability.
42
+ */
43
+ tags?: string[];
44
+ /**
45
+ * Optional example prompts demonstrating how to invoke this skill.
46
+ * Included in the agent card only when non-empty.
47
+ */
48
+ examples?: string[];
49
+ }
50
+ /**
51
+ * Agent identity and capabilities advertised via the A2A Agent Card.
52
+ *
53
+ * This interface captures all fields that appear in the public-facing agent
54
+ * card served at `/.well-known/agent-card.json`. Orchestrators and callers
55
+ * use this metadata to discover the agent's name, supported modes,
56
+ * streaming capability, and available skills.
57
+ */
58
+ export interface AgentCardConfig {
59
+ /**
60
+ * Human-readable agent name.
61
+ * Displayed in orchestrator UIs and agent discovery listings.
62
+ */
63
+ name: string;
64
+ /**
65
+ * Agent description shown to orchestrators and callers.
66
+ * Should concisely explain the agent's purpose and domain expertise.
67
+ */
68
+ description: string;
69
+ /**
70
+ * A2A protocol version this agent supports.
71
+ * @default "0.3.0"
72
+ */
73
+ protocolVersion?: string;
74
+ /**
75
+ * Agent software version string.
76
+ * @default "1.0.0"
77
+ */
78
+ version?: string;
79
+ /**
80
+ * Skills this agent exposes to callers.
81
+ * Each skill represents a discrete capability advertised in the agent card.
82
+ */
83
+ skills?: SkillConfig[];
84
+ /**
85
+ * Supported input content modes.
86
+ * @default ["text"]
87
+ */
88
+ defaultInputModes?: string[];
89
+ /**
90
+ * Supported output content modes.
91
+ * @default ["text"]
92
+ */
93
+ defaultOutputModes?: string[];
94
+ /**
95
+ * Whether the agent supports streaming responses.
96
+ * @default true
97
+ */
98
+ streaming?: boolean;
99
+ /**
100
+ * Whether the agent supports push notifications.
101
+ * @default false
102
+ */
103
+ pushNotifications?: boolean;
104
+ /**
105
+ * Enable state transition history capability advertisement.
106
+ *
107
+ * @deprecated This capability is not implemented in the A2A v1.0 spec and
108
+ * was removed. Kept for backward compatibility only — value is ignored.
109
+ * The agent card builder always sets this to `false`.
110
+ * @default false
111
+ */
112
+ stateTransitionHistory?: boolean;
113
+ /**
114
+ * Agent provider information.
115
+ * Identifies the organization responsible for this agent deployment.
116
+ */
117
+ provider?: {
118
+ /** Organization name. */
119
+ organization: string;
120
+ /** Optional URL for the provider's website or documentation. */
121
+ url?: string;
122
+ };
123
+ }
124
+ /**
125
+ * Network and server settings for the A2A HTTP server.
126
+ *
127
+ * Controls the bind address, port, and the externally-advertised hostname
128
+ * and protocol used when constructing agent card endpoint URLs.
129
+ */
130
+ export interface ServerConfig {
131
+ /**
132
+ * TCP port the A2A server listens on.
133
+ * @default 3000
134
+ */
135
+ port?: number;
136
+ /**
137
+ * Network interface bind address.
138
+ * @default "0.0.0.0"
139
+ */
140
+ hostname?: string;
141
+ /**
142
+ * Hostname advertised in agent card endpoint URLs.
143
+ * Set to the machine's public IP or `"host.containers.internal"` for Docker.
144
+ * @default "localhost"
145
+ */
146
+ advertiseHost?: string;
147
+ /**
148
+ * Protocol used in advertised endpoint URLs.
149
+ * Set to `"https"` when deployed behind TLS or a TLS-terminating reverse
150
+ * proxy. The A2A spec requires HTTPS for production deployments.
151
+ * @default "http"
152
+ */
153
+ advertiseProtocol?: "http" | "https";
154
+ }
155
+ /**
156
+ * Session lifecycle management settings.
157
+ *
158
+ * Controls how the session manager maps A2A `contextId` values to backend
159
+ * sessions, including TTL-based expiration and periodic cleanup.
160
+ */
161
+ export interface SessionConfig {
162
+ /**
163
+ * Prefix applied to session titles when creating new backend sessions.
164
+ * @default "A2A Session"
165
+ */
166
+ titlePrefix?: string;
167
+ /**
168
+ * Whether to reuse existing sessions for the same A2A `contextId`.
169
+ * When enabled, subsequent requests with the same contextId are routed
170
+ * to the previously created backend session.
171
+ * @default true
172
+ */
173
+ reuseByContext?: boolean;
174
+ /**
175
+ * Session time-to-live in milliseconds.
176
+ * Sessions exceeding this age are removed during the next cleanup cycle.
177
+ * @default 3_600_000 (1 hour)
178
+ */
179
+ ttl?: number;
180
+ /**
181
+ * Interval in milliseconds between session cleanup sweeps.
182
+ * @default 300_000 (5 minutes)
183
+ */
184
+ cleanupInterval?: number;
185
+ }
186
+ /**
187
+ * Base feature flags shared across all wrapper projects.
188
+ *
189
+ * Contains only the flags that are common to every A2A wrapper. Individual
190
+ * wrapper projects extend this interface with backend-specific flags
191
+ * (e.g. `autoApprovePermissions` in a2a-opencode).
192
+ */
193
+ export interface BaseFeatureFlags {
194
+ /**
195
+ * Whether to stream artifact chunks individually (A2A spec-correct behavior)
196
+ * or buffer and send a single artifact (inspector-compatible).
197
+ * @default false (buffered)
198
+ */
199
+ streamArtifactChunks?: boolean;
200
+ }
201
+ /**
202
+ * Timeout settings for various agent operations.
203
+ *
204
+ * Unifies timeout fields from both wrapper projects into a single interface.
205
+ * All values are in milliseconds.
206
+ */
207
+ export interface TimeoutConfig {
208
+ /**
209
+ * Maximum time to wait for a single prompt/request to complete.
210
+ * @default 300_000 (5 minutes)
211
+ */
212
+ prompt?: number;
213
+ /**
214
+ * Polling interval for fallback transport when SSE is unavailable.
215
+ * @default 2_000 (2 seconds)
216
+ */
217
+ pollingInterval?: number;
218
+ /**
219
+ * Interval between health check pings. Set to `0` to disable.
220
+ * @default 30_000 (30 seconds)
221
+ */
222
+ healthCheck?: number;
223
+ }
224
+ /**
225
+ * Logging settings for the agent runtime.
226
+ *
227
+ * Controls the minimum log level emitted by the {@link Logger} instance.
228
+ */
229
+ export interface LoggingConfig {
230
+ /**
231
+ * Minimum log level: `"debug"`, `"info"`, `"warn"`, or `"error"`.
232
+ * @default "info"
233
+ */
234
+ level?: string;
235
+ }
236
+ /**
237
+ * Base MCP server configuration with a type discriminator.
238
+ *
239
+ * Provides the minimal shared shape for MCP server entries. Each wrapper
240
+ * project defines its own concrete MCP server config types (e.g. stdio,
241
+ * HTTP, SSE, remote) that extend or satisfy this base interface.
242
+ */
243
+ export interface BaseMcpServerConfig {
244
+ /**
245
+ * Transport type discriminator.
246
+ * Wrapper projects use this to distinguish between server kinds
247
+ * (e.g. `"stdio"`, `"http"`, `"sse"`, `"local"`, `"remote"`).
248
+ */
249
+ type: string;
250
+ /**
251
+ * Whether this MCP server is enabled on startup.
252
+ * @default true
253
+ */
254
+ enabled?: boolean;
255
+ }
256
+ /**
257
+ * Base agent configuration parameterized by backend-specific config.
258
+ *
259
+ * This generic interface represents the complete, resolved configuration for
260
+ * an A2A agent wrapper. It includes all shared sections (agent card, server,
261
+ * session, features, timeouts, logging, MCP) plus a generic `backend` field
262
+ * that each wrapper project fills with its own backend-specific type
263
+ * (e.g. `CopilotConfig`, `OpenCodeConfig`).
264
+ *
265
+ * Wrapper projects compose their full config type as:
266
+ * ```typescript
267
+ * type AgentConfig = BaseAgentConfig<CopilotConfig>;
268
+ * ```
269
+ *
270
+ * @typeParam TBackend - Wrapper-specific backend configuration type.
271
+ * Defaults to `Record<string, unknown>` for contexts where the backend
272
+ * type is not yet known or not relevant.
273
+ */
274
+ export interface BaseAgentConfig<TBackend = Record<string, unknown>> {
275
+ /**
276
+ * Agent card identity and capabilities advertised via the A2A protocol.
277
+ * Drives the contents of `/.well-known/agent-card.json`.
278
+ */
279
+ agentCard: AgentCardConfig;
280
+ /**
281
+ * Network and server settings controlling bind address, port, and
282
+ * externally-advertised endpoint URLs.
283
+ */
284
+ server: ServerConfig;
285
+ /**
286
+ * Backend-specific configuration section.
287
+ * Replaces the project-specific `copilot` / `opencode` fields from the
288
+ * original wrapper projects, enabling full type safety via generics.
289
+ */
290
+ backend: TBackend;
291
+ /**
292
+ * Session lifecycle management settings including TTL, cleanup interval,
293
+ * and contextId-based session reuse.
294
+ */
295
+ session: SessionConfig;
296
+ /**
297
+ * Base feature flags shared across all wrappers.
298
+ * Wrapper projects may extend {@link BaseFeatureFlags} with additional
299
+ * backend-specific flags.
300
+ */
301
+ features: BaseFeatureFlags;
302
+ /**
303
+ * Timeout settings for prompt execution, polling, and health checks.
304
+ */
305
+ timeouts: TimeoutConfig;
306
+ /**
307
+ * Logging configuration controlling the minimum log level.
308
+ */
309
+ logging: LoggingConfig;
310
+ /**
311
+ * MCP servers to register with the backend at startup.
312
+ * Keys are server names, values are server configurations satisfying
313
+ * the {@link BaseMcpServerConfig} base interface.
314
+ */
315
+ mcp: Record<string, BaseMcpServerConfig>;
316
+ }
317
+ //# sourceMappingURL=types.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/config/types.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,17 @@
1
+ /**
2
+ * Base Configuration Types
3
+ *
4
+ * Shared TypeScript interfaces for all configurable aspects of an A2A agent
5
+ * wrapper deployment. These types unify the common configuration sections
6
+ * found in both `a2a-copilot` and `a2a-opencode`, providing a single source
7
+ * of truth for agent card identity, server networking, session lifecycle,
8
+ * feature flags, timeouts, logging, and MCP server definitions.
9
+ *
10
+ * Wrapper-specific configuration (e.g. `CopilotConfig`, `OpenCodeConfig`) is
11
+ * injected via the `TBackend` generic parameter on {@link BaseAgentConfig},
12
+ * keeping this module completely decoupled from any particular backend.
13
+ *
14
+ * @module config/types
15
+ */
16
+ export {};
17
+ //# sourceMappingURL=types.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/config/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG"}