@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.
- package/AGENTS.md +43 -12
- package/CHANGELOG.md +524 -0
- package/README.md +32 -15
- package/SECURITY.md +6 -5
- package/bin/connecta.mjs +5 -1
- package/dist/activity.d.ts +10 -3
- package/dist/activity.js +10 -1
- package/dist/advertised-schema.js +53 -0
- package/dist/artifacts/connector.d.ts +55 -0
- package/dist/artifacts/connector.js +724 -0
- package/dist/artifacts/document.js +76 -0
- package/dist/artifacts/guide.js +140 -0
- package/dist/artifacts/html-scan.js +329 -0
- package/dist/artifacts/json.js +68 -0
- package/dist/artifacts/kv-store.d.ts +20 -0
- package/dist/artifacts/kv-store.js +140 -0
- package/dist/artifacts/markdown.js +449 -0
- package/dist/artifacts/module.d.ts +37 -0
- package/dist/artifacts/module.js +60 -0
- package/dist/artifacts/operations.d.ts +195 -0
- package/dist/artifacts/operations.js +944 -0
- package/dist/artifacts/refresh.d.ts +53 -0
- package/dist/artifacts/refresh.js +235 -0
- package/dist/artifacts/routes.js +194 -0
- package/dist/artifacts/types.d.ts +214 -0
- package/dist/artifacts/types.js +22 -0
- package/dist/artifacts/validate.d.ts +62 -0
- package/dist/artifacts/validate.js +652 -0
- package/dist/artifacts.d.ts +6 -0
- package/dist/artifacts.js +9 -0
- package/dist/auth/downstream-oauth.js +490 -106
- package/dist/call-admission.js +139 -113
- package/dist/catalog-service.js +152 -106
- package/dist/catalog.js +297 -38
- package/dist/concurrency.js +24 -23
- package/dist/connector-access.d.ts +18 -4
- package/dist/connector-access.js +65 -20
- package/dist/connector-caller.d.ts +8 -0
- package/dist/connector-caller.js +19 -0
- package/dist/connector-scope.js +6 -37
- package/dist/connectors/api.d.ts +2 -2
- package/dist/connectors/remote-mcp.d.ts +6 -5
- package/dist/connectors/remote-mcp.js +330 -240
- package/dist/credential-contract.d.ts +9 -0
- package/dist/credential-rules.js +2 -2
- package/dist/credentials.d.ts +6 -1
- package/dist/credentials.js +45 -3
- package/dist/errors.d.ts +16 -1
- package/dist/errors.js +28 -0
- package/dist/execute.js +745 -282
- package/dist/executor-admission.d.ts +11 -1
- package/dist/executor-admission.js +145 -63
- package/dist/executors/quickjs-runtime.js +4 -2
- package/dist/executors/quickjs.js +255 -212
- package/dist/fix-prompt.js +37 -0
- package/dist/index.d.ts +72 -7
- package/dist/index.js +281 -26
- package/dist/invocation.js +371 -286
- package/dist/meta-tools.js +213 -94
- package/dist/module-contracts.d.ts +21 -1
- package/dist/oauth-callback-outcome.js +94 -0
- package/dist/oauth-sealing.js +29 -0
- package/dist/operator-ui/fix-prompts.js +87 -0
- package/dist/operator-ui/generated.js +2 -2
- package/dist/operator-ui/model.d.ts +103 -1
- package/dist/operator-ui/setup-commands.js +53 -0
- package/dist/operator-ui/view.js +128 -3
- package/dist/program-source.js +321 -0
- package/dist/providers/notion.js +2 -2
- package/dist/providers/revenuecat.js +32 -5
- package/dist/providers/stripe.d.ts +3 -2
- package/dist/providers/vercel.js +1 -1
- package/dist/registry.d.ts +43 -7
- package/dist/registry.js +434 -288
- package/dist/resumable.js +1291 -0
- package/dist/routes/activity.js +74 -154
- package/dist/routes/actor-labels.js +114 -0
- package/dist/routes/credentials.js +196 -163
- package/dist/routes/mcp.js +228 -112
- package/dist/routes/oauth-management.js +73 -71
- package/dist/routes/oauth.js +44 -16
- package/dist/routes/operator.js +83 -0
- package/dist/routes/shared.d.ts +25 -1
- package/dist/routes/shared.js +20 -2
- package/dist/routes/ui-data.js +211 -0
- package/dist/routes/ui.js +76 -35
- package/dist/run-journal.js +347 -0
- package/dist/runtime/admission.js +43 -0
- package/dist/runtime/call-admission.js +67 -0
- package/dist/runtime/connector-scope.js +72 -0
- package/dist/runtime/run.js +174 -0
- package/dist/runtime/services.js +130 -0
- package/dist/runtime/shared-read.js +106 -0
- package/dist/runtime/storage.js +66 -0
- package/dist/server.js +137 -89
- package/dist/skills.js +28 -9
- package/dist/storage/file.js +39 -2
- package/dist/storage/memory.js +28 -16
- package/dist/timeout.js +39 -43
- package/dist/tool-safety.d.ts +27 -1
- package/dist/tool-safety.js +31 -0
- package/dist/types.d.ts +45 -7
- package/dist/ui.d.ts +25 -4
- package/dist/ui.js +77 -167
- package/dist/url-safety.js +157 -0
- package/dist/version.d.ts +1 -1
- package/dist/version.js +1 -1
- package/documentation/architecture.md +367 -16
- package/documentation/auth.md +163 -2
- package/documentation/code-mode.md +274 -56
- package/documentation/meta-tools.md +200 -44
- package/ethos.md +46 -47
- package/examples/worker/AGENTS.md +6 -0
- package/examples/worker/README.md +224 -14
- package/examples/worker/src/d1-activity-row.ts +14 -2
- package/examples/worker/src/d1-activity.ts +4 -2
- package/examples/worker/src/d1-storage.ts +116 -0
- package/examples/worker/src/index.ts +42 -7
- package/examples/worker/src/r2-artifact-blobs.ts +29 -0
- package/examples/worker/wrangler.jsonc +21 -5
- package/package.json +16 -4
- package/templates/node/AGENTS.md +9 -2
- package/templates/node/README.md +31 -3
- package/templates/node/package.json +1 -1
- package/templates/node/src/index.ts +27 -0
- package/dist/auth/downstream-oauth.d.ts +0 -200
- package/dist/catalog-fingerprint.d.ts +0 -19
- package/dist/catalog-limits.d.ts +0 -9
- package/dist/catalog-service.d.ts +0 -263
- package/dist/catalog.d.ts +0 -87
- package/dist/concurrency.d.ts +0 -3
- package/dist/connectors/guarded-fetch.d.ts +0 -96
- package/dist/credential-rules.d.ts +0 -85
- package/dist/execute.d.ts +0 -154
- package/dist/executor-result.d.ts +0 -10
- package/dist/executors/quickjs-child.d.ts +0 -1
- package/dist/executors/quickjs-protocol.d.ts +0 -67
- package/dist/favicon.d.ts +0 -1
- package/dist/identity.d.ts +0 -4
- package/dist/invocation.d.ts +0 -74
- package/dist/mcp-result.d.ts +0 -8
- package/dist/meta-tools.d.ts +0 -129
- package/dist/operator-ui/generated.d.ts +0 -2
- package/dist/operator-ui/view.d.ts +0 -188
- package/dist/result-shapes.d.ts +0 -13
- package/dist/retired-toolkits.d.ts +0 -2
- package/dist/routes/activity.d.ts +0 -2
- package/dist/routes/credentials.d.ts +0 -2
- package/dist/routes/mcp.d.ts +0 -10
- package/dist/routes/oauth-management.d.ts +0 -2
- package/dist/routes/oauth.d.ts +0 -2
- package/dist/routes/ui.d.ts +0 -2
- package/dist/server.d.ts +0 -9
- package/dist/skills.d.ts +0 -44
- 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>;
|
package/dist/identity.d.ts
DELETED
|
@@ -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>;
|
package/dist/invocation.d.ts
DELETED
|
@@ -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 {};
|
package/dist/mcp-result.d.ts
DELETED
|
@@ -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;
|
package/dist/meta-tools.d.ts
DELETED
|
@@ -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,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 {};
|
package/dist/result-shapes.d.ts
DELETED
|
@@ -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
|
-
}
|