@zackbart/connecta 0.24.4 → 0.25.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 (107) hide show
  1. package/AGENTS.md +40 -10
  2. package/CHANGELOG.md +253 -0
  3. package/dist/advertised-schema.js +53 -0
  4. package/dist/auth/downstream-oauth.js +490 -106
  5. package/dist/call-admission.js +139 -113
  6. package/dist/catalog-service.js +141 -105
  7. package/dist/catalog.js +258 -33
  8. package/dist/concurrency.js +24 -23
  9. package/dist/connector-scope.js +6 -37
  10. package/dist/connectors/api.d.ts +2 -2
  11. package/dist/connectors/remote-mcp.d.ts +6 -5
  12. package/dist/connectors/remote-mcp.js +317 -241
  13. package/dist/credential-contract.d.ts +9 -0
  14. package/dist/credential-rules.js +2 -2
  15. package/dist/credentials.d.ts +6 -1
  16. package/dist/credentials.js +45 -3
  17. package/dist/execute.js +363 -257
  18. package/dist/executor-admission.js +67 -50
  19. package/dist/executors/quickjs-runtime.js +4 -2
  20. package/dist/executors/quickjs.js +251 -210
  21. package/dist/fix-prompt.js +37 -0
  22. package/dist/index.d.ts +10 -1
  23. package/dist/index.js +51 -20
  24. package/dist/invocation.js +324 -285
  25. package/dist/meta-tools.js +206 -92
  26. package/dist/oauth-callback-outcome.js +94 -0
  27. package/dist/oauth-sealing.js +29 -0
  28. package/dist/operator-ui/fix-prompts.js +87 -0
  29. package/dist/operator-ui/generated.js +2 -2
  30. package/dist/operator-ui/model.d.ts +46 -1
  31. package/dist/operator-ui/setup-commands.js +53 -0
  32. package/dist/operator-ui/view.js +38 -2
  33. package/dist/program-source.js +205 -0
  34. package/dist/providers/notion.js +2 -2
  35. package/dist/providers/revenuecat.js +32 -5
  36. package/dist/providers/stripe.d.ts +3 -2
  37. package/dist/providers/vercel.js +1 -1
  38. package/dist/registry.d.ts +1 -1
  39. package/dist/registry.js +305 -260
  40. package/dist/routes/activity.js +120 -137
  41. package/dist/routes/credentials.js +174 -163
  42. package/dist/routes/mcp.js +129 -70
  43. package/dist/routes/oauth-management.js +60 -71
  44. package/dist/routes/oauth.js +44 -16
  45. package/dist/routes/operator.js +82 -0
  46. package/dist/routes/shared.d.ts +2 -0
  47. package/dist/routes/ui-data.js +210 -0
  48. package/dist/routes/ui.js +64 -32
  49. package/dist/runtime/admission.js +43 -0
  50. package/dist/runtime/call-admission.js +67 -0
  51. package/dist/runtime/connector-scope.js +72 -0
  52. package/dist/runtime/run.js +174 -0
  53. package/dist/runtime/services.js +130 -0
  54. package/dist/runtime/storage.js +66 -0
  55. package/dist/server.js +111 -89
  56. package/dist/skills.js +1 -1
  57. package/dist/storage/file.js +39 -2
  58. package/dist/storage/memory.js +28 -16
  59. package/dist/timeout.js +17 -47
  60. package/dist/types.d.ts +27 -7
  61. package/dist/ui.d.ts +16 -2
  62. package/dist/ui.js +50 -166
  63. package/dist/url-safety.js +157 -0
  64. package/dist/version.d.ts +1 -1
  65. package/dist/version.js +1 -1
  66. package/documentation/architecture.md +184 -10
  67. package/documentation/auth.md +80 -0
  68. package/documentation/code-mode.md +69 -24
  69. package/documentation/meta-tools.md +164 -27
  70. package/ethos.md +44 -47
  71. package/examples/worker/README.md +51 -5
  72. package/examples/worker/src/d1-storage.ts +116 -0
  73. package/examples/worker/src/index.ts +6 -6
  74. package/examples/worker/wrangler.jsonc +16 -4
  75. package/package.json +11 -3
  76. package/templates/node/package.json +1 -1
  77. package/dist/auth/downstream-oauth.d.ts +0 -200
  78. package/dist/catalog-fingerprint.d.ts +0 -19
  79. package/dist/catalog-limits.d.ts +0 -9
  80. package/dist/catalog-service.d.ts +0 -263
  81. package/dist/catalog.d.ts +0 -87
  82. package/dist/concurrency.d.ts +0 -3
  83. package/dist/connectors/guarded-fetch.d.ts +0 -96
  84. package/dist/credential-rules.d.ts +0 -85
  85. package/dist/execute.d.ts +0 -154
  86. package/dist/executor-result.d.ts +0 -10
  87. package/dist/executors/quickjs-child.d.ts +0 -1
  88. package/dist/executors/quickjs-protocol.d.ts +0 -67
  89. package/dist/favicon.d.ts +0 -1
  90. package/dist/identity.d.ts +0 -4
  91. package/dist/invocation.d.ts +0 -74
  92. package/dist/mcp-result.d.ts +0 -8
  93. package/dist/meta-tools.d.ts +0 -129
  94. package/dist/operator-ui/generated.d.ts +0 -2
  95. package/dist/operator-ui/view.d.ts +0 -188
  96. package/dist/result-shapes.d.ts +0 -13
  97. package/dist/retired-toolkits.d.ts +0 -2
  98. package/dist/routes/activity.d.ts +0 -2
  99. package/dist/routes/credentials.d.ts +0 -2
  100. package/dist/routes/mcp.d.ts +0 -10
  101. package/dist/routes/oauth-management.d.ts +0 -2
  102. package/dist/routes/oauth.d.ts +0 -2
  103. package/dist/routes/ui.d.ts +0 -2
  104. package/dist/server.d.ts +0 -9
  105. package/dist/skills.d.ts +0 -44
  106. package/dist/timeout.d.ts +0 -21
  107. package/dist/tool-safety.d.ts +0 -9
@@ -1,96 +0,0 @@
1
- import type { ConnectorContext } from "../types.js";
2
- /** The methods a hand-written provider surface actually uses. */
3
- type GuardedMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
4
- export interface GuardedRequest {
5
- method: GuardedMethod;
6
- /**
7
- * Provider-relative path beginning with one `/`, resolved against the base
8
- * URL's own path. Never an absolute URL, and never carrying `?` or `#` —
9
- * query parameters go in `query`, where they are encoded rather than parsed.
10
- */
11
- path: string;
12
- /** Search parameters; `undefined` values are dropped, others stringified. */
13
- query?: Record<string, string | number | boolean | undefined>;
14
- /**
15
- * Per-request headers. `undefined` values are dropped, and a header that
16
- * collides with an authentication header is refused rather than allowed to
17
- * shadow it.
18
- */
19
- headers?: Record<string, string | undefined>;
20
- /** JSON request body. Serialized here, with the `Content-Type` to match. */
21
- body?: unknown;
22
- /**
23
- * A pre-framed body — `FormData`, text, bytes. Mutually exclusive with
24
- * `body`, and no `Content-Type` is supplied: multipart needs `fetch` to pick
25
- * the boundary, and anything else knows its own type.
26
- */
27
- rawBody?: BodyInit;
28
- }
29
- /**
30
- * One downstream response, read under the connector's byte ceiling.
31
- *
32
- * The accessors are the whole read surface — there is no escape to the
33
- * underlying `Response`, because an unbounded `.text()` on it is exactly the
34
- * mistake this type exists to remove. `status`, `ok`, and `headers` are the
35
- * raw facts a provider mapper needs to make its own classification.
36
- */
37
- interface GuardedResponse {
38
- readonly status: number;
39
- readonly ok: boolean;
40
- readonly headers: Headers;
41
- /** The body as bytes. */
42
- bytes(): Promise<Uint8Array>;
43
- /** The body decoded as UTF-8. */
44
- text(): Promise<string>;
45
- /** The body parsed as JSON; `undefined` for an empty body, throws on junk. */
46
- json(): Promise<unknown>;
47
- /** Parse JSON while distinguishing malformed content from transport failure. */
48
- jsonResult(): Promise<{
49
- value: unknown;
50
- } | {
51
- parseError: unknown;
52
- }>;
53
- }
54
- /** Parse delta-seconds or an HTTP-date into a non-negative wait window. */
55
- export declare function retryAfterMs(headers: Headers): number | undefined;
56
- /**
57
- * Turn one response into the provider's own result, or throw the provider's
58
- * own typed failure. This is where status codes acquire meaning, and it is
59
- * always the provider's code.
60
- */
61
- type GuardedResponseMapper<T> = (response: GuardedResponse, ctx: ConnectorContext) => T | Promise<T>;
62
- export interface GuardedFetchOptions {
63
- /**
64
- * Provider name as it appears in normalized failure prose — "Cloudflare",
65
- * "Notion". Used for messages only; it is never parsed.
66
- */
67
- provider: string;
68
- /**
69
- * Absolute base URL. Its origin and path prefix are the confinement: every
70
- * request resolves beneath it or is refused.
71
- */
72
- baseUrl: string;
73
- /**
74
- * Headers proving the caller's identity, resolved once per request. Throwing
75
- * a typed `auth_required` from here is the documented way to report a
76
- * missing credential — the helper has no opinion about what a credential is.
77
- */
78
- authenticate: (ctx: ConnectorContext) => Record<string, string> | Promise<Record<string, string>>;
79
- /** Constant headers sent with every request — `Accept`, an API version. */
80
- headers?: Record<string, string>;
81
- /**
82
- * Ceiling on the response body, in bytes. Required, because a default here
83
- * would be the helper guessing on a provider's behalf: what counts as an
84
- * absurd response is a fact about the API, not about HTTP.
85
- */
86
- maxResponseBytes: number;
87
- }
88
- /** Send one guarded request and map its response with provider knowledge. */
89
- export type GuardedTransport = <T>(request: GuardedRequest, ctx: ConnectorContext, map: GuardedResponseMapper<T>) => Promise<T>;
90
- /**
91
- * Build the transport a connector sends every request through. `maxResponseBytes`
92
- * is required rather than defaulted: what counts as an absurd response is a fact
93
- * about the API, not about HTTP.
94
- */
95
- export declare function guardedFetch(options: GuardedFetchOptions): GuardedTransport;
96
- export {};
@@ -1,85 +0,0 @@
1
- import type { Connector, ConnectorCredentialConfig } from "./types.js";
2
- /** Which hook a testable credential is checked with. */
3
- type CredentialTestMode = "single" | "multiple";
4
- /** Operator-safe explanation shared by every surface that detects shape drift. */
5
- export declare const STORED_CREDENTIAL_SHAPE_MISMATCH_ERROR = "Stored credential fields do not match this connector's current declaration. Replace the credential before using or testing this connector.";
6
- export type StoredCredentialShape = {
7
- state: "missing";
8
- } | {
9
- state: "valid";
10
- mode: CredentialTestMode;
11
- /**
12
- * Stored keys the connector no longer declares, sorted. Harmless — the
13
- * credential works — but worth telling an operator about, since nothing
14
- * else in `/ui` can show a field the declaration has stopped naming.
15
- */
16
- undeclared: string[];
17
- } | {
18
- state: "mismatch";
19
- mode: CredentialTestMode;
20
- message: typeof STORED_CREDENTIAL_SHAPE_MISMATCH_ERROR;
21
- };
22
- /**
23
- * Compare a connector's current declaration with the keys in its stored
24
- * credential. Values are deliberately ignored: callers may pass decrypted
25
- * values or `/credentials`' masked field metadata and get the same answer.
26
- *
27
- * The test is CONTAINMENT, not equality: the stored key set is compatible when
28
- * it holds every field currently declared — the reserved `value` key for a
29
- * single-value declaration, every declared name for a named one. Anything the
30
- * declaration asks for and the vault does not have is `mismatch`, which is
31
- * precisely what a renamed field, a newly added field, or a swap between the
32
- * two shapes produces. The swap needs no special case: `value` is never one of
33
- * the declared names, so single→named and named→single each leave the declared
34
- * side unsatisfied. An empty stored map (reachable through a hand-written
35
- * plaintext) satisfies nothing and is a mismatch too.
36
- *
37
- * Extra keys are NOT drift. They are what *dropping* a field leaves behind, and
38
- * every accessor a connector actually uses — `ctx.credential.get("apiKey")`,
39
- * `getAll().apiKey` — keeps returning the right secret across that redeploy.
40
- * Calling it drift would order an operator to re-enter a working secret that
41
- * many providers will not reissue in readable form. The leftovers come back as
42
- * `undeclared` instead, for a surface to mention without blocking anything.
43
- */
44
- export declare function storedCredentialShape(config: ConnectorCredentialConfig, stored: Readonly<Record<string, unknown>> | null): StoredCredentialShape;
45
- /**
46
- * The one sentence describing leftover stored fields, so every surface words it
47
- * the same way. Names only — the values stay in the vault, and a field name from
48
- * a previous declaration is not a secret. Deliberately reassuring: nothing is
49
- * broken, and the only thing an operator gains by acting is that a connector
50
- * iterating `getAll()` stops seeing a field its code no longer knows about.
51
- */
52
- export declare function describeUndeclaredCredentialFields(fields: string[]): string;
53
- /** A declared credential shape whose only test hook cannot test it. */
54
- export interface CredentialTestMismatch {
55
- /** The shape the connector declared. */
56
- shape: CredentialTestMode;
57
- /** The hook it implements, which that shape cannot use. */
58
- hook: "testCredential" | "testCredentials";
59
- }
60
- export interface CredentialTestRule {
61
- /** The hook to call, or null when this credential cannot be tested at all. */
62
- mode: CredentialTestMode | null;
63
- /** Set only when the sole implemented hook is the one the shape cannot use. */
64
- mismatch?: CredentialTestMismatch;
65
- }
66
- /**
67
- * The one rule deciding whether a connector's credential can be tested — read
68
- * by /credentials' `testable` flag, by `POST /ui/credentials/<id>/test` when
69
- * it picks a hook, and by the construction-time mismatch warning, so those
70
- * three cannot drift apart.
71
- *
72
- * The declared credential *shape* selects the hook: named `credential.fields`
73
- * are tested as a set by `testCredentials`, a single-value `credential` by
74
- * `testCredential` on the vault's reserved `value` field. The other hook is
75
- * never substituted — it would be handed a shape the connector never declared —
76
- * so a connector implementing only the mismatched hook is not testable, and
77
- * says so at construction rather than under an operator's click.
78
- */
79
- export declare function credentialTestRule(connector: Pick<Connector, "credential" | "testCredential" | "testCredentials">): CredentialTestRule;
80
- /**
81
- * One clause naming a mismatch, shared by the startup warning and the test
82
- * route's 400 so an operator reads the same explanation in both places.
83
- */
84
- export declare function describeCredentialTestMismatch(mismatch: CredentialTestMismatch): string;
85
- export {};
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;