@zackbart/connecta 0.24.4 → 0.26.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 (155) hide show
  1. package/AGENTS.md +43 -12
  2. package/CHANGELOG.md +524 -0
  3. package/README.md +32 -15
  4. package/SECURITY.md +6 -5
  5. package/bin/connecta.mjs +5 -1
  6. package/dist/activity.d.ts +10 -3
  7. package/dist/activity.js +10 -1
  8. package/dist/advertised-schema.js +53 -0
  9. package/dist/artifacts/connector.d.ts +55 -0
  10. package/dist/artifacts/connector.js +724 -0
  11. package/dist/artifacts/document.js +76 -0
  12. package/dist/artifacts/guide.js +140 -0
  13. package/dist/artifacts/html-scan.js +329 -0
  14. package/dist/artifacts/json.js +68 -0
  15. package/dist/artifacts/kv-store.d.ts +20 -0
  16. package/dist/artifacts/kv-store.js +140 -0
  17. package/dist/artifacts/markdown.js +449 -0
  18. package/dist/artifacts/module.d.ts +37 -0
  19. package/dist/artifacts/module.js +60 -0
  20. package/dist/artifacts/operations.d.ts +195 -0
  21. package/dist/artifacts/operations.js +944 -0
  22. package/dist/artifacts/refresh.d.ts +53 -0
  23. package/dist/artifacts/refresh.js +235 -0
  24. package/dist/artifacts/routes.js +194 -0
  25. package/dist/artifacts/types.d.ts +214 -0
  26. package/dist/artifacts/types.js +22 -0
  27. package/dist/artifacts/validate.d.ts +62 -0
  28. package/dist/artifacts/validate.js +652 -0
  29. package/dist/artifacts.d.ts +6 -0
  30. package/dist/artifacts.js +9 -0
  31. package/dist/auth/downstream-oauth.js +490 -106
  32. package/dist/call-admission.js +139 -113
  33. package/dist/catalog-service.js +152 -106
  34. package/dist/catalog.js +297 -38
  35. package/dist/concurrency.js +24 -23
  36. package/dist/connector-access.d.ts +18 -4
  37. package/dist/connector-access.js +65 -20
  38. package/dist/connector-caller.d.ts +8 -0
  39. package/dist/connector-caller.js +19 -0
  40. package/dist/connector-scope.js +6 -37
  41. package/dist/connectors/api.d.ts +2 -2
  42. package/dist/connectors/remote-mcp.d.ts +6 -5
  43. package/dist/connectors/remote-mcp.js +330 -240
  44. package/dist/credential-contract.d.ts +9 -0
  45. package/dist/credential-rules.js +2 -2
  46. package/dist/credentials.d.ts +6 -1
  47. package/dist/credentials.js +45 -3
  48. package/dist/errors.d.ts +16 -1
  49. package/dist/errors.js +28 -0
  50. package/dist/execute.js +745 -282
  51. package/dist/executor-admission.d.ts +11 -1
  52. package/dist/executor-admission.js +145 -63
  53. package/dist/executors/quickjs-runtime.js +4 -2
  54. package/dist/executors/quickjs.js +255 -212
  55. package/dist/fix-prompt.js +37 -0
  56. package/dist/index.d.ts +72 -7
  57. package/dist/index.js +281 -26
  58. package/dist/invocation.js +371 -286
  59. package/dist/meta-tools.js +213 -94
  60. package/dist/module-contracts.d.ts +21 -1
  61. package/dist/oauth-callback-outcome.js +94 -0
  62. package/dist/oauth-sealing.js +29 -0
  63. package/dist/operator-ui/fix-prompts.js +87 -0
  64. package/dist/operator-ui/generated.js +2 -2
  65. package/dist/operator-ui/model.d.ts +103 -1
  66. package/dist/operator-ui/setup-commands.js +53 -0
  67. package/dist/operator-ui/view.js +128 -3
  68. package/dist/program-source.js +321 -0
  69. package/dist/providers/notion.js +2 -2
  70. package/dist/providers/revenuecat.js +32 -5
  71. package/dist/providers/stripe.d.ts +3 -2
  72. package/dist/providers/vercel.js +1 -1
  73. package/dist/registry.d.ts +43 -7
  74. package/dist/registry.js +434 -288
  75. package/dist/resumable.js +1291 -0
  76. package/dist/routes/activity.js +74 -154
  77. package/dist/routes/actor-labels.js +114 -0
  78. package/dist/routes/credentials.js +196 -163
  79. package/dist/routes/mcp.js +228 -112
  80. package/dist/routes/oauth-management.js +73 -71
  81. package/dist/routes/oauth.js +44 -16
  82. package/dist/routes/operator.js +83 -0
  83. package/dist/routes/shared.d.ts +25 -1
  84. package/dist/routes/shared.js +20 -2
  85. package/dist/routes/ui-data.js +211 -0
  86. package/dist/routes/ui.js +76 -35
  87. package/dist/run-journal.js +347 -0
  88. package/dist/runtime/admission.js +43 -0
  89. package/dist/runtime/call-admission.js +67 -0
  90. package/dist/runtime/connector-scope.js +72 -0
  91. package/dist/runtime/run.js +174 -0
  92. package/dist/runtime/services.js +130 -0
  93. package/dist/runtime/shared-read.js +106 -0
  94. package/dist/runtime/storage.js +66 -0
  95. package/dist/server.js +137 -89
  96. package/dist/skills.js +28 -9
  97. package/dist/storage/file.js +39 -2
  98. package/dist/storage/memory.js +28 -16
  99. package/dist/timeout.js +39 -43
  100. package/dist/tool-safety.d.ts +27 -1
  101. package/dist/tool-safety.js +31 -0
  102. package/dist/types.d.ts +45 -7
  103. package/dist/ui.d.ts +25 -4
  104. package/dist/ui.js +77 -167
  105. package/dist/url-safety.js +157 -0
  106. package/dist/version.d.ts +1 -1
  107. package/dist/version.js +1 -1
  108. package/documentation/architecture.md +367 -16
  109. package/documentation/auth.md +163 -2
  110. package/documentation/code-mode.md +274 -56
  111. package/documentation/meta-tools.md +200 -44
  112. package/ethos.md +46 -47
  113. package/examples/worker/AGENTS.md +6 -0
  114. package/examples/worker/README.md +224 -14
  115. package/examples/worker/src/d1-activity-row.ts +14 -2
  116. package/examples/worker/src/d1-activity.ts +4 -2
  117. package/examples/worker/src/d1-storage.ts +116 -0
  118. package/examples/worker/src/index.ts +42 -7
  119. package/examples/worker/src/r2-artifact-blobs.ts +29 -0
  120. package/examples/worker/wrangler.jsonc +21 -5
  121. package/package.json +16 -4
  122. package/templates/node/AGENTS.md +9 -2
  123. package/templates/node/README.md +31 -3
  124. package/templates/node/package.json +1 -1
  125. package/templates/node/src/index.ts +27 -0
  126. package/dist/auth/downstream-oauth.d.ts +0 -200
  127. package/dist/catalog-fingerprint.d.ts +0 -19
  128. package/dist/catalog-limits.d.ts +0 -9
  129. package/dist/catalog-service.d.ts +0 -263
  130. package/dist/catalog.d.ts +0 -87
  131. package/dist/concurrency.d.ts +0 -3
  132. package/dist/connectors/guarded-fetch.d.ts +0 -96
  133. package/dist/credential-rules.d.ts +0 -85
  134. package/dist/execute.d.ts +0 -154
  135. package/dist/executor-result.d.ts +0 -10
  136. package/dist/executors/quickjs-child.d.ts +0 -1
  137. package/dist/executors/quickjs-protocol.d.ts +0 -67
  138. package/dist/favicon.d.ts +0 -1
  139. package/dist/identity.d.ts +0 -4
  140. package/dist/invocation.d.ts +0 -74
  141. package/dist/mcp-result.d.ts +0 -8
  142. package/dist/meta-tools.d.ts +0 -129
  143. package/dist/operator-ui/generated.d.ts +0 -2
  144. package/dist/operator-ui/view.d.ts +0 -188
  145. package/dist/result-shapes.d.ts +0 -13
  146. package/dist/retired-toolkits.d.ts +0 -2
  147. package/dist/routes/activity.d.ts +0 -2
  148. package/dist/routes/credentials.d.ts +0 -2
  149. package/dist/routes/mcp.d.ts +0 -10
  150. package/dist/routes/oauth-management.d.ts +0 -2
  151. package/dist/routes/oauth.d.ts +0 -2
  152. package/dist/routes/ui.d.ts +0 -2
  153. package/dist/server.d.ts +0 -9
  154. package/dist/skills.d.ts +0 -44
  155. package/dist/timeout.d.ts +0 -21
package/dist/execute.d.ts DELETED
@@ -1,154 +0,0 @@
1
- import type { McpServer } from "@modelcontextprotocol/server";
2
- import type { ActivityRequestContext } from "./activity.js";
3
- import type { DeferredWork } from "./connector-scope.js";
4
- import { type ToolResult } from "./meta-tools.js";
5
- import { InvocationFailure } from "./invocation.js";
6
- import type { RegistryView } from "./registry.js";
7
- import type { Executor, ExecutorProvider, Logger } from "./types.js";
8
- /** Complete entries plus an exact omission count, all inside this byte cap. */
9
- export declare const CONNECTOR_INVENTORY_MAX_BYTES = 256;
10
- /**
11
- * Default budgets for `connecta.emit`. The byte budget is a transport bound,
12
- * not a context bound — emitted image/audio blocks reach the model as media,
13
- * not base64 text — so it sits far above the 24k return-value guard: room for
14
- * two or three real screenshots after base64's 4/3 inflation, well short of a
15
- * file-hosting ambition (design record M5).
16
- */
17
- export declare const EXECUTE_MAX_EMITTED_BYTES = 4000000;
18
- export declare const EXECUTE_MAX_EMITTED_BLOCKS = 32;
19
- type ExecuteDiagnosticOperation = "search" | "describe" | "call";
20
- interface ExecuteOperationDiagnostics {
21
- operation: ExecuteDiagnosticOperation;
22
- count: number;
23
- failures: number;
24
- durationMs: number;
25
- resultBytes: number;
26
- catalogMs: number;
27
- connectorMs: number;
28
- }
29
- declare class ExecuteDiagnostics {
30
- private readonly started;
31
- private readonly operations;
32
- admissionMs: number;
33
- setupMs: number;
34
- executorWallMs: number;
35
- private emitted?;
36
- /** Numbers only, per R8 — and only once something was emitted, so a
37
- * non-emitting run's diagnostics stay byte-for-byte what they were. */
38
- recordEmitted(count: number, bytes: number): void;
39
- private stats;
40
- recordCatalog(operation: "search" | "describe", durationMs: number, ok: boolean, result?: unknown): void;
41
- recordCall(outcome: {
42
- ok: boolean;
43
- durationMs: number;
44
- timing: {
45
- catalogMs: number;
46
- connectorMs: number;
47
- };
48
- value?: unknown;
49
- }): void;
50
- finish(): {
51
- timing: {
52
- totalMs: number;
53
- admissionMs: number;
54
- setupMs: number;
55
- executorWallMs: number;
56
- catalogMs: number;
57
- connectorMs: number;
58
- };
59
- operations: ExecuteOperationDiagnostics[];
60
- emitted?: {
61
- count: number;
62
- bytes: number;
63
- };
64
- };
65
- }
66
- /**
67
- * One MCP content block a program may emit. The complete set, by design:
68
- * `resource` and `resource_link` are refused in ethos.md — pointers get
69
- * followed, and connecta serves no resources for them to point at.
70
- */
71
- export type EmittedBlock = {
72
- type: "text";
73
- text: string;
74
- } | {
75
- type: "image";
76
- data: string;
77
- mimeType: string;
78
- } | {
79
- type: "audio";
80
- data: string;
81
- mimeType: string;
82
- };
83
- export declare class EmitCollector {
84
- private readonly maxBytes;
85
- private readonly maxBlocks;
86
- private readonly diagnostics?;
87
- readonly blocks: EmittedBlock[];
88
- bytes: number;
89
- constructor(maxBytes: number, maxBlocks: number, diagnostics?: ExecuteDiagnostics | undefined);
90
- accept(raw: unknown): void;
91
- }
92
- /**
93
- * Expose one host provider and typed guest errors. Catalogs load only when
94
- * the program calls a tool or asks search/describe.
95
- */
96
- export declare function buildSandboxProviders(registry: RegistryView, baseUrl: string, _logger: Logger, activity?: ActivityRequestContext, limits?: {
97
- signal?: AbortSignal | undefined;
98
- maxHostCalls?: number | undefined;
99
- hostCallTimeoutMs?: number | undefined;
100
- discoveryConcurrency?: number | undefined;
101
- /** Per-connector deadline for in-program catalog probes. Default 30_000. */
102
- probeTimeoutMs?: number | undefined;
103
- onInvocationFailure?: ((failure: InvocationFailure) => void) | undefined;
104
- diagnostics?: ExecuteDiagnostics | undefined;
105
- /**
106
- * Where `connecta.emit` collects. The handler that will deliver the
107
- * blocks owns it; without one, emit fails loudly rather than accept
108
- * blocks nobody will ever return.
109
- */
110
- emitCollector?: EmitCollector | undefined;
111
- /** Runtime-owned tail for stale catalog refreshes. */
112
- defer?: DeferredWork | undefined;
113
- }): Promise<ExecutorProvider[]>;
114
- /** The execute_code handler. Exported for direct testing. */
115
- export declare function createExecuteTool(registry: RegistryView, baseUrl: string, executor: Executor, logger: Logger, activity?: ActivityRequestContext, config?: {
116
- discoveryConcurrency?: number | undefined;
117
- probeTimeoutMs?: number | undefined;
118
- maxEmittedBytes?: number | undefined;
119
- maxEmittedBlocks?: number | undefined;
120
- maxHostCalls?: number | undefined;
121
- hostCallTimeoutMs?: number | undefined;
122
- defer?: DeferredWork | undefined;
123
- }): ({ code, diagnostics: diagnosticsRequested }: {
124
- code: string;
125
- diagnostics?: boolean;
126
- }, options?: {
127
- signal?: AbortSignal;
128
- }) => Promise<ToolResult>;
129
- /** Register the execute_code meta-tool. Only called when an executor is configured. */
130
- export declare function registerExecuteTool(server: McpServer, registry: RegistryView, ctx: {
131
- baseUrl: string;
132
- executor: Executor;
133
- logger: Logger;
134
- activity?: ActivityRequestContext | undefined;
135
- requestSignal?: AbortSignal | undefined;
136
- discoveryConcurrency?: number | undefined;
137
- /**
138
- * The deployment's configured per-connector probe deadline. Programs probe
139
- * the same downstream catalogs the top-level tools do, so an operator who
140
- * tightened `discovery.probeTimeoutMs` gets it honored inside the sandbox
141
- * too rather than silently falling back to the 30s default.
142
- */
143
- probeTimeoutMs?: number | undefined;
144
- /** Aggregate serialized-byte budget for connecta.emit. Default 4_000_000. */
145
- maxEmittedBytes?: number | undefined;
146
- /** Block-count budget for connecta.emit. Default 32. */
147
- maxEmittedBlocks?: number | undefined;
148
- /** Host calls one program may make. Default 20. */
149
- maxHostCalls?: number | undefined;
150
- /** Deadline per host call in milliseconds. Default 15_000. */
151
- hostCallTimeoutMs?: number | undefined;
152
- defer?: DeferredWork | undefined;
153
- }): void;
154
- export {};
@@ -1,10 +0,0 @@
1
- import type { ExecuteResult } from "./types.js";
2
- export declare const MAX_EXECUTE_LOG_CHARS = 4000;
3
- export declare function serializeResultText(value: unknown): string;
4
- export declare function guardExecuteResultValue(value: unknown): unknown;
5
- export declare function truncateExecuteText(text: string, max: number): string;
6
- /**
7
- * Apply the public execute_code result/log policy before a child result enters
8
- * IPC. The parent repeats the guard for third-party Executor implementations.
9
- */
10
- export declare function prepareExecuteResultForTransport(outcome: ExecuteResult): ExecuteResult;
@@ -1 +0,0 @@
1
- export {};
@@ -1,67 +0,0 @@
1
- import type { ExecuteResult } from "../types.js";
2
- import type { QuickJsRuntimeOptions } from "./quickjs-runtime.js";
3
- export declare const MAX_QUICKJS_IPC_BYTES: number;
4
- export declare const MAX_QUICKJS_LOG_TRANSPORT_BYTES: number;
5
- /** Preserve #84's stopgap before a host value enters the child/WASM process. */
6
- export declare const MAX_QUICKJS_HOST_RPC_BYTES: number;
7
- export interface RunPayload {
8
- id: number;
9
- code: string;
10
- providers: Array<{
11
- name: string;
12
- prelude?: string;
13
- }>;
14
- options: QuickJsRuntimeOptions;
15
- }
16
- export type ParentToChildMessage = {
17
- type: "run";
18
- payloadJson: string;
19
- } | {
20
- type: "host-result";
21
- jobId: number;
22
- callId: number;
23
- payloadJson: string;
24
- };
25
- export type ChildToParentMessage = {
26
- type: "ready";
27
- } | {
28
- type: "host-call";
29
- jobId: number;
30
- callId: number;
31
- payloadJson: string;
32
- } | {
33
- type: "log";
34
- jobId: number;
35
- payloadJson: string;
36
- } | {
37
- type: "result";
38
- jobId: number;
39
- payloadJson: string;
40
- };
41
- export interface HostCallPayload {
42
- namespace: string;
43
- functionName: string;
44
- args: unknown[];
45
- }
46
- export type HostResultPayload = {
47
- ok: true;
48
- value: unknown;
49
- } | {
50
- ok: false;
51
- error: string;
52
- };
53
- export interface ExecutionPayload {
54
- outcome: ExecuteResult;
55
- /**
56
- * Set by the runtime on wall-clock expiry. The parent recycles the child on
57
- * this flag, never on error text a guest can fabricate.
58
- */
59
- timedOut?: boolean;
60
- }
61
- export declare function hostCallLabel(payload: {
62
- namespace: string;
63
- functionName: string;
64
- args: unknown[];
65
- }): string;
66
- export declare function serializedBytes(text: string): number;
67
- export declare function stringifyBounded(value: unknown, label: string, limit?: number): string;
package/dist/favicon.d.ts DELETED
@@ -1 +0,0 @@
1
- export declare const CONNECTA_FAVICON_ICO: Uint8Array<ArrayBufferLike>;
@@ -1,4 +0,0 @@
1
- import type { IdentityReference } from "./types.js";
2
- export declare function validIdentityReference(value: IdentityReference | undefined): value is IdentityReference;
3
- /** Deterministic pseudonymous partition; raw emails and ids do not enter keys. */
4
- export declare function identityStorageKey(identity: IdentityReference): Promise<string>;
@@ -1,74 +0,0 @@
1
- import { type ActivityCallSource, type ActivityRequestContext, type AgentFriction } from "./activity.js";
2
- import { CatalogService, type ResolvedCatalogTool } from "./catalog-service.js";
3
- import { type CallErrorDetails } from "./errors.js";
4
- import { type RegistryView } from "./registry.js";
5
- export interface InvocationTiming {
6
- catalogMs: number;
7
- admissionMs: number;
8
- connectorMs: number;
9
- resultProcessingMs: number;
10
- totalMs: number;
11
- }
12
- interface InvocationBase {
13
- durationMs: number;
14
- attempts: number;
15
- timing: InvocationTiming;
16
- resolved?: ResolvedCatalogTool;
17
- }
18
- export type InvocationOutcome<T> = (InvocationBase & {
19
- ok: true;
20
- value: T;
21
- resolved: ResolvedCatalogTool;
22
- }) | (InvocationBase & {
23
- ok: false;
24
- error: CallErrorDetails;
25
- });
26
- export interface InvocationContext<T> {
27
- source: ActivityCallSource;
28
- allowDestructive?: boolean;
29
- timeoutMs?: number;
30
- requestSignal?: AbortSignal;
31
- unwrapResult?: boolean;
32
- /**
33
- * Caller-owned result policy. MCP applies result paging here; code mode
34
- * normally accepts the already-unwrapped value unchanged.
35
- */
36
- processResult?: (value: unknown, resolved: ResolvedCatalogTool) => T | Promise<T>;
37
- /**
38
- * Optional payload-free friction class derived from a *successful* result —
39
- * today only an oversized one that had to be paged. It is deliberately not an
40
- * `errorCode`: the call succeeded, and a consumer that keys its dashboards on
41
- * "has an error code" must not count a truncation as a failure.
42
- */
43
- activityFriction?: (value: T) => AgentFriction | undefined;
44
- /**
45
- * Called after address/catalog/safety admission and before the first provider
46
- * attempt. Code mode uses it for its host-call budget.
47
- */
48
- beforeDispatch?: () => void;
49
- }
50
- export declare class InvocationFailure extends Error {
51
- readonly details: CallErrorDetails;
52
- readonly code: string;
53
- readonly retryable: boolean;
54
- readonly retryAfterMs: number | undefined;
55
- readonly connector: string | undefined;
56
- readonly operation: string | undefined;
57
- readonly recovery: CallErrorDetails["recovery"];
58
- readonly nextAction: CallErrorDetails["nextAction"];
59
- readonly retry: string | undefined;
60
- constructor(details: CallErrorDetails);
61
- }
62
- /**
63
- * Shared downstream invocation engine. Address/catalog resolution is delegated
64
- * to the request-local CatalogService; every remaining call semantic lives
65
- * here so MCP and code mode cannot drift independently.
66
- */
67
- export declare class InvocationService {
68
- private readonly registry;
69
- private readonly catalog;
70
- private readonly activity?;
71
- constructor(registry: RegistryView, catalog: CatalogService, activity?: ActivityRequestContext | undefined);
72
- invoke<T = unknown>(address: string, args: unknown, context: InvocationContext<T>): Promise<InvocationOutcome<T>>;
73
- }
74
- export {};
@@ -1,8 +0,0 @@
1
- import type { Connector } from "./types.js";
2
- /**
3
- * Unwrap an MCP CallToolResult into an ordinary JavaScript value:
4
- * `toolResult` wins when present, then `structuredContent`; all-text content is
5
- * JSON-parsed when possible. Downstream `isError` results become exceptions.
6
- * Non-MCP connectors already return plain values.
7
- */
8
- export declare function unwrapMcpResult(kind: Connector["kind"], result: unknown): unknown;
@@ -1,129 +0,0 @@
1
- import type { McpServer } from "@modelcontextprotocol/server";
2
- import type { ActivityRequestContext } from "./activity.js";
3
- import { MAX_DESCRIBE_ADDRESSES, MAX_DISCOVERY_RESULT_BYTES, MAX_SEARCH_LIMIT } from "./catalog-service.js";
4
- import type { DeferredWork } from "./connector-scope.js";
5
- import { type RegistryView } from "./registry.js";
6
- export { MAX_DESCRIBE_ADDRESSES, MAX_DISCOVERY_RESULT_BYTES, MAX_SEARCH_LIMIT, };
7
- interface TextContent {
8
- type: "text";
9
- text: string;
10
- }
11
- export interface ToolResult {
12
- content: TextContent[];
13
- isError?: boolean;
14
- structuredContent?: Record<string, unknown>;
15
- [x: string]: unknown;
16
- }
17
- export declare function jsonResult(obj: unknown, text?: string): ToolResult;
18
- export declare function errorResult(message: string): ToolResult;
19
- /**
20
- * Move a byte `offset` back to the nearest UTF-8 codepoint boundary in
21
- * `[0, offset]`, so decoding from it never starts mid-character (which emits
22
- * U+FFFD for the severed tail).
23
- *
24
- * Backwards, never forwards: re-serving a few bytes the caller already has is
25
- * recoverable, silently skipping the rest of a character is not. Offsets the
26
- * server itself produced (`nextOffset`) are already boundaries and come back
27
- * unchanged, so this only moves an offset a client computed on its own
28
- * (issue #38). An offset at or past `bytes.length` is left alone — there is no
29
- * character there to split.
30
- */
31
- export declare function alignStartToCharBoundary(bytes: Uint8Array, offset: number): number;
32
- /** End boundary for UTF-8-safe, forward-progressing result pages. See
33
- * documentation/meta-tools.md#result-representation. */
34
- export declare function alignEndToCharBoundary(bytes: Uint8Array, offset: number, end: number, total: number): number;
35
- export interface SearchArgs {
36
- query?: string;
37
- connector?: string;
38
- safety?: "readOnly" | "approvalRequired" | "all";
39
- limit?: number;
40
- offset?: number;
41
- fullDescriptions?: boolean;
42
- includeSchemas?: "compact" | "json";
43
- }
44
- type ResultMode = "mcp" | "value";
45
- export interface CallArgs {
46
- address: string;
47
- args?: Record<string, unknown>;
48
- resultMode?: ResultMode;
49
- timeoutMs?: number;
50
- /** Include connector/catalog/result-processing timing segments. */
51
- diagnostics?: boolean;
52
- }
53
- export interface DestructiveCallArgs extends CallArgs {
54
- /** Short model-authored context for the host's approval UI; never downstream input. */
55
- reason?: string;
56
- }
57
- export interface GetResultArgs {
58
- id: string;
59
- /**
60
- * Byte offset to page from; a whole number >= 0, aligned back to the nearest
61
- * character boundary and reported as the response's `offset`. Defaults to 0.
62
- */
63
- offset?: number;
64
- /** Page size in bytes; a whole number >= 1. Defaults to the deployment cap. */
65
- maxBytes?: number;
66
- }
67
- export interface AuthorizeArgs {
68
- connector: string;
69
- force?: boolean;
70
- }
71
- export interface SkillArgs {
72
- name?: string;
73
- }
74
- /**
75
- * Every meta-tool handler over a registry, one per registered tool. Exported for
76
- * direct testing; registerMetaTools() wires the six explicit tools onto an
77
- * McpServer. `opts.defaultToolTimeoutMs` supplies a deadline for calls that
78
- * don't carry one. (execute_code is registered separately by
79
- * registerExecuteTool, and builds its own services over the same registry.)
80
- *
81
- * What execute_code shares with these handlers is the services layer beneath
82
- * them — `CatalogService` and `InvocationService` — not the handlers, which no
83
- * in-program path calls.
84
- *
85
- * Deployment-wide result-size caps are read off the registry view rather than
86
- * passed in: `ConnectaConfig.calls.maxResultBytes` and its per-connector
87
- * override each have one runtime source of truth.
88
- */
89
- export declare function createMetaTools(registry: RegistryView, baseUrl: string, opts?: {
90
- /** Deadline applied when a call passes no `timeoutMs`. Off when unset. */
91
- defaultToolTimeoutMs?: number | undefined;
92
- /** Per-connector deadline for the search/describe probe fan-out. Default 30_000. */
93
- probeTimeoutMs?: number | undefined;
94
- /** Maximum simultaneous connector discovery operations. Default 4. */
95
- discoveryConcurrency?: number | undefined;
96
- activity?: ActivityRequestContext | undefined;
97
- canManageAuth?: ((id: string) => boolean) | undefined;
98
- credentialHandoffUrl?: string | undefined;
99
- /** Inbound request cancellation shared by every call this request makes. */
100
- requestSignal?: AbortSignal | undefined;
101
- /** Runtime-owned tail for stale catalog refreshes. */
102
- defer?: DeferredWork | undefined;
103
- }): {
104
- skills(args?: SkillArgs): Promise<ToolResult>;
105
- searchTools(args: SearchArgs): Promise<ToolResult>;
106
- callTool(args: CallArgs): Promise<ToolResult>;
107
- callDestructiveTool(args: DestructiveCallArgs): Promise<ToolResult>;
108
- getResult(args: GetResultArgs): Promise<ToolResult>;
109
- authorizeConnector(args: AuthorizeArgs): Promise<ToolResult>;
110
- };
111
- /**
112
- * Register the six explicit meta-tools onto an McpServer instance.
113
- * `registerExecuteTool` adds the seventh, `execute_code`. Broad discovery and
114
- * multi-call work uses discovery and ordinary JavaScript promises inside a
115
- * program, which `execute_code` builds over the same
116
- * `CatalogService` and `InvocationService` these handlers use — one shared
117
- * services layer, two adapters above it.
118
- */
119
- export declare function registerMetaTools(server: McpServer, registry: RegistryView, ctx: {
120
- baseUrl: string;
121
- defaultToolTimeoutMs?: number | undefined;
122
- probeTimeoutMs?: number | undefined;
123
- discoveryConcurrency?: number | undefined;
124
- activity?: ActivityRequestContext | undefined;
125
- canManageAuth?: ((id: string) => boolean) | undefined;
126
- credentialHandoffUrl?: string | undefined;
127
- requestSignal?: AbortSignal | undefined;
128
- defer?: DeferredWork | undefined;
129
- }): void;
@@ -1,2 +0,0 @@
1
- export declare const OPERATOR_UI_CSS: string;
2
- export declare const OPERATOR_UI_SCRIPT: string;
@@ -1,188 +0,0 @@
1
- import type { CatalogDriftReport } from "../types.js";
2
- import type { CredentialManagementCapability, UiConnector, UiData } from "./model.js";
3
- /**
4
- * Everything the operator app knows, and every rule for changing it, with no
5
- * DOM in sight. The components render this and nothing else, so the questions
6
- * that matter — what a page shows while it loads, what an identity change
7
- * erases, whether a value may become an href — are answered by functions a test
8
- * can call directly rather than by reading rendered markup back out of a
9
- * browser.
10
- */
11
- export type OperatorPage = "connections" | "activity";
12
- export declare const OPERATOR_PAGES: readonly OperatorPage[];
13
- export declare const PAGE_META: Readonly<Record<OperatorPage, {
14
- path: string;
15
- label: string;
16
- }>>;
17
- export declare function pageForPath(path: string): OperatorPage;
18
- export interface UiActivityActor {
19
- kind?: string;
20
- id?: string;
21
- namespace?: string;
22
- label?: string;
23
- }
24
- export interface UiActivityEvent {
25
- occurredAt: string;
26
- actor?: UiActivityActor;
27
- connectorId: string;
28
- toolName: string;
29
- address: string;
30
- source: string;
31
- outcome: string;
32
- durationMs: number;
33
- attempts: number;
34
- errorCode?: string;
35
- friction?: string;
36
- }
37
- /** A message with the tone that decides its live region: status or alert. */
38
- export interface Notice {
39
- message: string;
40
- tone: "info" | "error";
41
- }
42
- export declare function info(message: string): Notice;
43
- export declare function failure(message: string): Notice;
44
- /**
45
- * A remote collection's four states, named once so every page spells them the
46
- * same way. `idle` is "nobody has asked yet" and is what makes a re-entered
47
- * page fetch again after an identity change.
48
- */
49
- type LoadPhase = "idle" | "loading" | "ready" | "error";
50
- export interface OperatorState {
51
- page: OperatorPage;
52
- /**
53
- * Bumped by every identity change. Async work captures it before awaiting and
54
- * throws its result away if the operator is no longer the one who asked —
55
- * the fence that keeps one identity's data off another identity's screen.
56
- */
57
- generation: number;
58
- /** `loading` until the first /ui/data answer decides gated or ready. */
59
- session: "loading" | "gated" | "ready";
60
- gate: Notice | null;
61
- /** True while a signed-in operator's /ui/data is in flight. */
62
- refreshing: boolean;
63
- /**
64
- * Element id the next render should focus. A rebuilt page has no stable node
65
- * to hand focus to from an event handler, so the request travels through
66
- * state and the shell spends it once the new markup exists.
67
- */
68
- pendingFocus: string | null;
69
- data: UiData | null;
70
- connectorFilter: string;
71
- oauthNotice: Notice | null;
72
- /** Connector id whose OAuth mutation is in flight. */
73
- oauthBusy: string | null;
74
- credentialNotice: Notice | null;
75
- /** Connector id whose credential form is open. */
76
- credentialEditing: string | null;
77
- /** Connector id whose credential mutation is in flight. */
78
- credentialBusy: string | null;
79
- activityPhase: LoadPhase;
80
- activityNotice: Notice | null;
81
- activityEvents: UiActivityEvent[];
82
- activityCursor: string | null;
83
- activitySearch: string;
84
- }
85
- export declare function initialState(page: OperatorPage): OperatorState;
86
- /**
87
- * Drop to the gate and forget the previous operator. Bumping the generation is
88
- * what makes the drop stick: work already in flight for the old identity
89
- * resolves into a state that no longer accepts it.
90
- */
91
- export declare function resetIdentity(state: OperatorState, gate?: Notice | null): OperatorState;
92
- /**
93
- * Leaving a page closes what should not survive it: a one-time secret, a half
94
- * typed credential, and the notices that answered the page just left.
95
- */
96
- export declare function withPage(state: OperatorState, page: OperatorPage): OperatorState;
97
- export declare function credentialUnavailableCopy(capability?: CredentialManagementCapability): string;
98
- export declare function connectorStatusLabel(status: string): string;
99
- export declare function toolCountLabel(count: number): string;
100
- /** The tone a status carries wherever it is rendered as a badge or a tile. */
101
- export type Tone = "ok" | "warn" | "danger" | "neutral";
102
- export declare function connectorStatusTone(status: string): Tone;
103
- /**
104
- * The deployment in four numbers, so the page answers "is anything wrong"
105
- * above the list instead of only inside it. `attention` is what an operator
106
- * can act on now; `unavailable` is what they cannot. A connector still loading
107
- * its catalog counts only toward `total`, since calling it connected or failed
108
- * would be a guess either way.
109
- */
110
- export interface ConnectorSummary {
111
- total: number;
112
- connected: number;
113
- attention: number;
114
- unavailable: number;
115
- tools: number;
116
- /** Connectors whose last observed catalog refresh differed from the manifest. */
117
- drifting: number;
118
- }
119
- export declare function summarizeConnectors(connectors: readonly UiConnector[]): ConnectorSummary;
120
- /**
121
- * The one line above the list. Connected and tool counts are always present;
122
- * the two counts an operator may have to act on appear only when they are not
123
- * zero, so a healthy deployment stays short.
124
- */
125
- export declare function connectorSummaryParts(summary: ConnectorSummary): Array<{
126
- text: string;
127
- tone: Tone;
128
- }>;
129
- /** Who owns this connector's downstream credentials, in two words. */
130
- export declare function authScopeLabel(scope: UiConnector["authScope"]): string;
131
- /**
132
- * What this identity may do with a connector, in one line. Being able to use it
133
- * is implied by seeing it at all, so the sentence covers authentication, which
134
- * is the part that differs between operators.
135
- */
136
- export declare function permissionLabel(connector: UiConnector): string;
137
- /**
138
- * Hosted-provider catalog drift, as an operator reads it
139
- * ([#343](https://github.com/zackbart/connecta/issues/343)).
140
- *
141
- * - `unavailable` — no refresh has been observed in this runtime, so there is
142
- * nothing to report. Deliberately not `clean`: "we have not looked" and "we
143
- * looked and it matches" are different answers, and only one of them is a
144
- * reason to stop worrying.
145
- * - `clean` — a refresh happened and every category counted zero.
146
- * - `warning` — a refresh happened and at least one category did not.
147
- */
148
- export type DriftState = "clean" | "warning" | "unavailable";
149
- export declare function driftTotal(drift?: CatalogDriftReport): number;
150
- export declare function driftState(drift?: CatalogDriftReport): DriftState;
151
- /** Every category with its count, so a clean report still shows its zeros. */
152
- export declare function driftCounts(drift?: CatalogDriftReport): Array<{
153
- key: string;
154
- label: string;
155
- count: number;
156
- }>;
157
- /** One line naming the state and when it was observed. Never what drifted. */
158
- export declare function driftSummary(drift?: CatalogDriftReport): string;
159
- /**
160
- * Only http/https may become a clickable href — the browser half of the gate
161
- * `src/ui.ts` applies before an authorizationUrl is ever serialized. A hostile
162
- * downstream that gets a `javascript:` URL past one of them still meets the
163
- * other, and the caller renders inert text instead of a link.
164
- */
165
- export declare function safeHttpHref(url: string | undefined): string | null;
166
- /** Locale timestamp, or "" for anything that is not a readable date. */
167
- export declare function formatDate(value?: string): string;
168
- export declare function actorLabel(actor?: UiActivityActor): string;
169
- /**
170
- * The stable id behind a friendly label, shown only when a label or namespace
171
- * could otherwise make two different people look like one.
172
- */
173
- export declare function actorStableId(actor?: UiActivityActor): string | null;
174
- export declare function filterActivity(events: UiActivityEvent[], query: string): UiActivityEvent[];
175
- /** Counts only. What the deployment ran, never what it sent or received. */
176
- export declare function activitySummary(events: UiActivityEvent[]): string;
177
- export declare function activityOutcomeClass(outcome: string): string;
178
- /** The one-line detail under an address: source, retries, and friction. */
179
- export declare function activityDetail(event: UiActivityEvent): string;
180
- export declare function credentialStateLabel(credential: {
181
- configured: boolean;
182
- fields?: unknown[];
183
- lastFour?: string;
184
- updatedAt?: string;
185
- }): string;
186
- /** Gate copy for each browser-auth shape, so the sign-in state is never a blank page. */
187
- export declare function gateCopy(kind: string, signedIn: boolean): string;
188
- export {};
@@ -1,13 +0,0 @@
1
- import type { JsonSchema, ToolDef } from "./types.js";
2
- /**
3
- * Passive, process-local output-shape learning. Provider declarations always
4
- * win; observations are an open, optional-field routing aid and never a
5
- * replacement contract.
6
- */
7
- export declare class ObservedOutputSchemas {
8
- private readonly entries;
9
- private cacheKey;
10
- private set;
11
- get(connectorId: string, definition: ToolDef): JsonSchema | undefined;
12
- observe(connectorId: string, definition: ToolDef, value: unknown): void;
13
- }
@@ -1,2 +0,0 @@
1
- /** Fail loudly when JavaScript callers pass the retired audience-scoping keys. */
2
- export declare function assertNoRetiredToolkitOptions(source: string, options: object): void;
@@ -1,2 +0,0 @@
1
- import { type RouteContext } from "./shared.js";
2
- export declare function routeActivity(context: RouteContext): Promise<Response | null>;
@@ -1,2 +0,0 @@
1
- import { type RouteContext } from "./shared.js";
2
- export declare function routeCredentials(context: RouteContext): Promise<Response | null>;