@anuma/agent-runtime 6.33.2 → 6.34.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/dist/index.d.mts +44 -0
- package/dist/index.d.ts +44 -0
- package/package.json +3 -3
package/dist/index.d.mts
CHANGED
|
@@ -3,12 +3,18 @@ export { ConnectorTokenGetterOpts } from '@anuma/sdk/tools';
|
|
|
3
3
|
import { LlmapiMessage } from '@anuma/sdk';
|
|
4
4
|
import { ToolConfig, StreamingTransport, ApiType, AutoExecutedToolResult } from '@anuma/sdk/server';
|
|
5
5
|
|
|
6
|
+
/** Parsed result of an incoming bearer token, returned by {@link extractGrantContext}. */
|
|
6
7
|
interface GrantContext {
|
|
8
|
+
/** Wallet address; the primary user identifier on the portal. */
|
|
7
9
|
userAddress: string;
|
|
10
|
+
/** OAuth `client_id` that owns the bearer, e.g. `"haven_v1"`. */
|
|
8
11
|
clientId: string;
|
|
12
|
+
/** Scopes the user granted to this client. */
|
|
9
13
|
scopes: string[];
|
|
14
|
+
/** Bearer token verbatim, for relaying to the portal. */
|
|
10
15
|
bearer: string;
|
|
11
16
|
}
|
|
17
|
+
/** Result of a mint call; HTTP failures, including 5xx after retries, are returned and network errors throw; `expiresAt` is unix ms. */
|
|
12
18
|
type MintResult = {
|
|
13
19
|
ok: true;
|
|
14
20
|
accessToken: string;
|
|
@@ -17,35 +23,52 @@ type MintResult = {
|
|
|
17
23
|
ok: false;
|
|
18
24
|
error: MintError;
|
|
19
25
|
};
|
|
26
|
+
/** Variants of `MintResult.error`, re-exported from `@anuma/sdk/tools`. */
|
|
20
27
|
type MintError = ConnectorMintError;
|
|
28
|
+
/** Returned by {@link PortalClient.listConnectors}; `connectedAt` is unix ms. */
|
|
21
29
|
interface ConnectorInfo {
|
|
22
30
|
oauthApp: string;
|
|
23
31
|
externalAccount?: string;
|
|
24
32
|
grantedScopes: string[];
|
|
25
33
|
connectedAt: number;
|
|
26
34
|
}
|
|
35
|
+
/** Argument shape for {@link PortalClient.createConnectTicket}. */
|
|
27
36
|
interface ConnectTicketOpts {
|
|
37
|
+
/** Logical provider, e.g. `"gmail"` or `"github"`. */
|
|
28
38
|
provider: string;
|
|
39
|
+
/** Scopes passed verbatim upstream (Google needs full `https://www.googleapis.com/auth/...` URLs); an empty array uses the provider's default scopes. */
|
|
29
40
|
requestedScopes: string[];
|
|
30
41
|
returnTo: string;
|
|
31
42
|
}
|
|
43
|
+
/** Result of a ticket-mint call; `expiresAt` is unix ms. */
|
|
32
44
|
interface ConnectTicket {
|
|
33
45
|
ticketId: string;
|
|
34
46
|
expiresAt: number;
|
|
35
47
|
connectUrl: string;
|
|
36
48
|
}
|
|
49
|
+
/** Typed wrapper over the portal HTTP API. */
|
|
37
50
|
interface PortalClient {
|
|
51
|
+
/** Mint an upstream access token for a logical provider; `access` defaults to the provider's standard level. */
|
|
38
52
|
mintConnectorToken(provider: string, access?: string): Promise<MintResult>;
|
|
53
|
+
/** List the user's connected connectors. */
|
|
39
54
|
listConnectors(): Promise<ConnectorInfo[]>;
|
|
55
|
+
/** Mint a connect ticket for redirecting the user to a connect flow. */
|
|
40
56
|
createConnectTicket(opts: ConnectTicketOpts): Promise<ConnectTicket>;
|
|
41
57
|
}
|
|
58
|
+
/** Options for {@link createPortalClient}. */
|
|
42
59
|
interface PortalClientOpts {
|
|
60
|
+
/** @defaultValue `process.env.ANUMA_PORTAL_URL`, then the production portal */
|
|
43
61
|
baseUrl?: string;
|
|
62
|
+
/** @defaultValue `globalThis.fetch` */
|
|
44
63
|
fetchImpl?: typeof fetch;
|
|
64
|
+
/** Per-request timeout. @defaultValue 5000 */
|
|
45
65
|
timeoutMs?: number;
|
|
66
|
+
/** Max attempts on 5xx and network errors. @defaultValue 3 */
|
|
46
67
|
maxRetries?: number;
|
|
68
|
+
/** Initial backoff before the second attempt. @defaultValue 100 */
|
|
47
69
|
retryBaseMs?: number;
|
|
48
70
|
}
|
|
71
|
+
/** Structurally typed incoming request; any HTTP framework satisfies it. */
|
|
49
72
|
interface IncomingRequest {
|
|
50
73
|
headers: {
|
|
51
74
|
authorization?: string;
|
|
@@ -53,6 +76,7 @@ interface IncomingRequest {
|
|
|
53
76
|
[key: string]: string | string[] | undefined;
|
|
54
77
|
};
|
|
55
78
|
}
|
|
79
|
+
/** Structured tool error; connector errors populate `provider`, others carry `message`. */
|
|
56
80
|
interface ToolErrorInfo {
|
|
57
81
|
code: string;
|
|
58
82
|
provider?: string;
|
|
@@ -66,48 +90,68 @@ interface ToolError {
|
|
|
66
90
|
error: ToolErrorInfo;
|
|
67
91
|
}
|
|
68
92
|
|
|
93
|
+
/** Discriminant for {@link AuthError}. */
|
|
69
94
|
type AuthErrorSubtype = "missing_bearer" | "invalid_bearer" | "expired" | "revoked";
|
|
95
|
+
/** Thrown by `extractGrantContext` when the bearer is missing, malformed, expired, or revoked. */
|
|
70
96
|
declare class AuthError extends Error {
|
|
71
97
|
readonly subtype: AuthErrorSubtype;
|
|
72
98
|
constructor(subtype: AuthErrorSubtype, message?: string);
|
|
73
99
|
}
|
|
74
100
|
|
|
75
101
|
type ExtractGrantContextOpts = Pick<PortalClientOpts, "baseUrl" | "fetchImpl" | "timeoutMs">;
|
|
102
|
+
/** Validate the request's bearer against the portal and return the parsed grant. @throws {@link AuthError} when the bearer is missing, malformed, expired, or revoked. */
|
|
76
103
|
declare function extractGrantContext(req: IncomingRequest, opts?: ExtractGrantContextOpts): Promise<GrantContext>;
|
|
77
104
|
|
|
105
|
+
/** Create a {@link PortalClient} that retries 5xx and network errors with jittered exponential backoff and never retries 4xx. */
|
|
78
106
|
declare function createPortalClient(bearer: string, opts?: PortalClientOpts): PortalClient;
|
|
79
107
|
|
|
80
108
|
declare function createConnectorTokenGetter(client: PortalClient, provider: string, opts?: ConnectorTokenGetterOpts): () => Promise<string | null>;
|
|
81
109
|
|
|
110
|
+
/** Minimal slice of `AgentConfig` this runtime depends on. */
|
|
82
111
|
interface AgentConfigLike {
|
|
83
112
|
model: {
|
|
84
113
|
default: string;
|
|
85
114
|
};
|
|
86
115
|
prompt: string;
|
|
87
116
|
}
|
|
117
|
+
/** Options for {@link runAgentRequest}. */
|
|
88
118
|
interface AgentRequestOpts {
|
|
119
|
+
/** Inbound request; only `headers.authorization` is read. */
|
|
89
120
|
request: IncomingRequest;
|
|
90
121
|
agent: AgentConfigLike;
|
|
91
122
|
messages: LlmapiMessage[];
|
|
123
|
+
/** Factories that receive the portal client and return `ToolConfig[]`. */
|
|
92
124
|
toolFactories?: Array<(portalClient: PortalClient) => ToolConfig[]>;
|
|
125
|
+
/** Overrides for the portal client, for test injection. */
|
|
93
126
|
portalClientOpts?: PortalClientOpts;
|
|
127
|
+
/** Streaming transport override forwarded to `runToolLoop`, for tests. */
|
|
94
128
|
transport?: StreamingTransport;
|
|
129
|
+
/** Portal base URL for chat completions; without a stub `transport` this hits the real portal. */
|
|
95
130
|
portalBaseUrl?: string;
|
|
131
|
+
/** LLM API strategy. @defaultValue `"auto"` */
|
|
96
132
|
apiType?: ApiType;
|
|
97
133
|
}
|
|
134
|
+
/** Token usage lifted off the LLM response. */
|
|
98
135
|
interface UsageSummary {
|
|
99
136
|
inputTokens?: number;
|
|
100
137
|
outputTokens?: number;
|
|
101
138
|
totalTokens?: number;
|
|
102
139
|
}
|
|
140
|
+
/** Result of {@link runAgentRequest}. */
|
|
103
141
|
interface AgentResponse {
|
|
142
|
+
/** Input messages, then an assistant `tool_calls` message and tool-result messages when tools ran, then the final assistant message if present. */
|
|
104
143
|
messages: LlmapiMessage[];
|
|
144
|
+
/** Connector errors lifted from tool results. */
|
|
105
145
|
toolErrors: ToolError[];
|
|
106
146
|
usage?: UsageSummary;
|
|
147
|
+
/** Grant context, for logging and tenant propagation. */
|
|
107
148
|
grant: GrantContext;
|
|
108
149
|
}
|
|
150
|
+
/** Lift tool results carrying the `__anuma_connector_error_v1` marker into structured `ToolError`s. */
|
|
109
151
|
declare function extractConnectorToolErrors(toolResults: AutoExecutedToolResult[] | undefined): ToolError[];
|
|
152
|
+
/** Default `requestAccess` for server agents: always throws, since they cannot drive interactive OAuth. */
|
|
110
153
|
declare function denyInteractive(): Promise<string | null>;
|
|
154
|
+
/** Handle one inbound agent request: validate the bearer, build the portal client and tools, run `runToolLoop`, and lift connector errors. @throws Error when the tool loop fails at the transport level. */
|
|
111
155
|
declare function runAgentRequest(opts: AgentRequestOpts): Promise<AgentResponse>;
|
|
112
156
|
|
|
113
157
|
export { type AgentConfigLike, type AgentRequestOpts, type AgentResponse, AuthError, type AuthErrorSubtype, type ConnectTicket, type ConnectTicketOpts, type ConnectorInfo, type ExtractGrantContextOpts, type GrantContext, type IncomingRequest, type MintError, type MintResult, type PortalClient, type PortalClientOpts, type ToolError, type ToolErrorInfo, type UsageSummary, createConnectorTokenGetter, createPortalClient, denyInteractive, extractConnectorToolErrors, extractGrantContext, runAgentRequest };
|
package/dist/index.d.ts
CHANGED
|
@@ -3,12 +3,18 @@ export { ConnectorTokenGetterOpts } from '@anuma/sdk/tools';
|
|
|
3
3
|
import { LlmapiMessage } from '@anuma/sdk';
|
|
4
4
|
import { ToolConfig, StreamingTransport, ApiType, AutoExecutedToolResult } from '@anuma/sdk/server';
|
|
5
5
|
|
|
6
|
+
/** Parsed result of an incoming bearer token, returned by {@link extractGrantContext}. */
|
|
6
7
|
interface GrantContext {
|
|
8
|
+
/** Wallet address; the primary user identifier on the portal. */
|
|
7
9
|
userAddress: string;
|
|
10
|
+
/** OAuth `client_id` that owns the bearer, e.g. `"haven_v1"`. */
|
|
8
11
|
clientId: string;
|
|
12
|
+
/** Scopes the user granted to this client. */
|
|
9
13
|
scopes: string[];
|
|
14
|
+
/** Bearer token verbatim, for relaying to the portal. */
|
|
10
15
|
bearer: string;
|
|
11
16
|
}
|
|
17
|
+
/** Result of a mint call; HTTP failures, including 5xx after retries, are returned and network errors throw; `expiresAt` is unix ms. */
|
|
12
18
|
type MintResult = {
|
|
13
19
|
ok: true;
|
|
14
20
|
accessToken: string;
|
|
@@ -17,35 +23,52 @@ type MintResult = {
|
|
|
17
23
|
ok: false;
|
|
18
24
|
error: MintError;
|
|
19
25
|
};
|
|
26
|
+
/** Variants of `MintResult.error`, re-exported from `@anuma/sdk/tools`. */
|
|
20
27
|
type MintError = ConnectorMintError;
|
|
28
|
+
/** Returned by {@link PortalClient.listConnectors}; `connectedAt` is unix ms. */
|
|
21
29
|
interface ConnectorInfo {
|
|
22
30
|
oauthApp: string;
|
|
23
31
|
externalAccount?: string;
|
|
24
32
|
grantedScopes: string[];
|
|
25
33
|
connectedAt: number;
|
|
26
34
|
}
|
|
35
|
+
/** Argument shape for {@link PortalClient.createConnectTicket}. */
|
|
27
36
|
interface ConnectTicketOpts {
|
|
37
|
+
/** Logical provider, e.g. `"gmail"` or `"github"`. */
|
|
28
38
|
provider: string;
|
|
39
|
+
/** Scopes passed verbatim upstream (Google needs full `https://www.googleapis.com/auth/...` URLs); an empty array uses the provider's default scopes. */
|
|
29
40
|
requestedScopes: string[];
|
|
30
41
|
returnTo: string;
|
|
31
42
|
}
|
|
43
|
+
/** Result of a ticket-mint call; `expiresAt` is unix ms. */
|
|
32
44
|
interface ConnectTicket {
|
|
33
45
|
ticketId: string;
|
|
34
46
|
expiresAt: number;
|
|
35
47
|
connectUrl: string;
|
|
36
48
|
}
|
|
49
|
+
/** Typed wrapper over the portal HTTP API. */
|
|
37
50
|
interface PortalClient {
|
|
51
|
+
/** Mint an upstream access token for a logical provider; `access` defaults to the provider's standard level. */
|
|
38
52
|
mintConnectorToken(provider: string, access?: string): Promise<MintResult>;
|
|
53
|
+
/** List the user's connected connectors. */
|
|
39
54
|
listConnectors(): Promise<ConnectorInfo[]>;
|
|
55
|
+
/** Mint a connect ticket for redirecting the user to a connect flow. */
|
|
40
56
|
createConnectTicket(opts: ConnectTicketOpts): Promise<ConnectTicket>;
|
|
41
57
|
}
|
|
58
|
+
/** Options for {@link createPortalClient}. */
|
|
42
59
|
interface PortalClientOpts {
|
|
60
|
+
/** @defaultValue `process.env.ANUMA_PORTAL_URL`, then the production portal */
|
|
43
61
|
baseUrl?: string;
|
|
62
|
+
/** @defaultValue `globalThis.fetch` */
|
|
44
63
|
fetchImpl?: typeof fetch;
|
|
64
|
+
/** Per-request timeout. @defaultValue 5000 */
|
|
45
65
|
timeoutMs?: number;
|
|
66
|
+
/** Max attempts on 5xx and network errors. @defaultValue 3 */
|
|
46
67
|
maxRetries?: number;
|
|
68
|
+
/** Initial backoff before the second attempt. @defaultValue 100 */
|
|
47
69
|
retryBaseMs?: number;
|
|
48
70
|
}
|
|
71
|
+
/** Structurally typed incoming request; any HTTP framework satisfies it. */
|
|
49
72
|
interface IncomingRequest {
|
|
50
73
|
headers: {
|
|
51
74
|
authorization?: string;
|
|
@@ -53,6 +76,7 @@ interface IncomingRequest {
|
|
|
53
76
|
[key: string]: string | string[] | undefined;
|
|
54
77
|
};
|
|
55
78
|
}
|
|
79
|
+
/** Structured tool error; connector errors populate `provider`, others carry `message`. */
|
|
56
80
|
interface ToolErrorInfo {
|
|
57
81
|
code: string;
|
|
58
82
|
provider?: string;
|
|
@@ -66,48 +90,68 @@ interface ToolError {
|
|
|
66
90
|
error: ToolErrorInfo;
|
|
67
91
|
}
|
|
68
92
|
|
|
93
|
+
/** Discriminant for {@link AuthError}. */
|
|
69
94
|
type AuthErrorSubtype = "missing_bearer" | "invalid_bearer" | "expired" | "revoked";
|
|
95
|
+
/** Thrown by `extractGrantContext` when the bearer is missing, malformed, expired, or revoked. */
|
|
70
96
|
declare class AuthError extends Error {
|
|
71
97
|
readonly subtype: AuthErrorSubtype;
|
|
72
98
|
constructor(subtype: AuthErrorSubtype, message?: string);
|
|
73
99
|
}
|
|
74
100
|
|
|
75
101
|
type ExtractGrantContextOpts = Pick<PortalClientOpts, "baseUrl" | "fetchImpl" | "timeoutMs">;
|
|
102
|
+
/** Validate the request's bearer against the portal and return the parsed grant. @throws {@link AuthError} when the bearer is missing, malformed, expired, or revoked. */
|
|
76
103
|
declare function extractGrantContext(req: IncomingRequest, opts?: ExtractGrantContextOpts): Promise<GrantContext>;
|
|
77
104
|
|
|
105
|
+
/** Create a {@link PortalClient} that retries 5xx and network errors with jittered exponential backoff and never retries 4xx. */
|
|
78
106
|
declare function createPortalClient(bearer: string, opts?: PortalClientOpts): PortalClient;
|
|
79
107
|
|
|
80
108
|
declare function createConnectorTokenGetter(client: PortalClient, provider: string, opts?: ConnectorTokenGetterOpts): () => Promise<string | null>;
|
|
81
109
|
|
|
110
|
+
/** Minimal slice of `AgentConfig` this runtime depends on. */
|
|
82
111
|
interface AgentConfigLike {
|
|
83
112
|
model: {
|
|
84
113
|
default: string;
|
|
85
114
|
};
|
|
86
115
|
prompt: string;
|
|
87
116
|
}
|
|
117
|
+
/** Options for {@link runAgentRequest}. */
|
|
88
118
|
interface AgentRequestOpts {
|
|
119
|
+
/** Inbound request; only `headers.authorization` is read. */
|
|
89
120
|
request: IncomingRequest;
|
|
90
121
|
agent: AgentConfigLike;
|
|
91
122
|
messages: LlmapiMessage[];
|
|
123
|
+
/** Factories that receive the portal client and return `ToolConfig[]`. */
|
|
92
124
|
toolFactories?: Array<(portalClient: PortalClient) => ToolConfig[]>;
|
|
125
|
+
/** Overrides for the portal client, for test injection. */
|
|
93
126
|
portalClientOpts?: PortalClientOpts;
|
|
127
|
+
/** Streaming transport override forwarded to `runToolLoop`, for tests. */
|
|
94
128
|
transport?: StreamingTransport;
|
|
129
|
+
/** Portal base URL for chat completions; without a stub `transport` this hits the real portal. */
|
|
95
130
|
portalBaseUrl?: string;
|
|
131
|
+
/** LLM API strategy. @defaultValue `"auto"` */
|
|
96
132
|
apiType?: ApiType;
|
|
97
133
|
}
|
|
134
|
+
/** Token usage lifted off the LLM response. */
|
|
98
135
|
interface UsageSummary {
|
|
99
136
|
inputTokens?: number;
|
|
100
137
|
outputTokens?: number;
|
|
101
138
|
totalTokens?: number;
|
|
102
139
|
}
|
|
140
|
+
/** Result of {@link runAgentRequest}. */
|
|
103
141
|
interface AgentResponse {
|
|
142
|
+
/** Input messages, then an assistant `tool_calls` message and tool-result messages when tools ran, then the final assistant message if present. */
|
|
104
143
|
messages: LlmapiMessage[];
|
|
144
|
+
/** Connector errors lifted from tool results. */
|
|
105
145
|
toolErrors: ToolError[];
|
|
106
146
|
usage?: UsageSummary;
|
|
147
|
+
/** Grant context, for logging and tenant propagation. */
|
|
107
148
|
grant: GrantContext;
|
|
108
149
|
}
|
|
150
|
+
/** Lift tool results carrying the `__anuma_connector_error_v1` marker into structured `ToolError`s. */
|
|
109
151
|
declare function extractConnectorToolErrors(toolResults: AutoExecutedToolResult[] | undefined): ToolError[];
|
|
152
|
+
/** Default `requestAccess` for server agents: always throws, since they cannot drive interactive OAuth. */
|
|
110
153
|
declare function denyInteractive(): Promise<string | null>;
|
|
154
|
+
/** Handle one inbound agent request: validate the bearer, build the portal client and tools, run `runToolLoop`, and lift connector errors. @throws Error when the tool loop fails at the transport level. */
|
|
111
155
|
declare function runAgentRequest(opts: AgentRequestOpts): Promise<AgentResponse>;
|
|
112
156
|
|
|
113
157
|
export { type AgentConfigLike, type AgentRequestOpts, type AgentResponse, AuthError, type AuthErrorSubtype, type ConnectTicket, type ConnectTicketOpts, type ConnectorInfo, type ExtractGrantContextOpts, type GrantContext, type IncomingRequest, type MintError, type MintResult, type PortalClient, type PortalClientOpts, type ToolError, type ToolErrorInfo, type UsageSummary, createConnectorTokenGetter, createPortalClient, denyInteractive, extractConnectorToolErrors, extractGrantContext, runAgentRequest };
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@anuma/agent-runtime",
|
|
3
|
-
"version": "6.
|
|
3
|
+
"version": "6.34.0",
|
|
4
4
|
"description": "Server-side runtime contract for Anuma agents — extractGrantContext, PortalClient, runAgentRequest.",
|
|
5
5
|
"main": "./dist/index.cjs",
|
|
6
6
|
"module": "./dist/index.mjs",
|
|
@@ -30,13 +30,13 @@
|
|
|
30
30
|
"access": "public"
|
|
31
31
|
},
|
|
32
32
|
"peerDependencies": {
|
|
33
|
-
"@anuma/sdk": "6.
|
|
33
|
+
"@anuma/sdk": "6.34.0"
|
|
34
34
|
},
|
|
35
35
|
"devDependencies": {
|
|
36
36
|
"tsup": "^8.5.1",
|
|
37
37
|
"typescript": "^5.9.3",
|
|
38
38
|
"vitest": "^4.1.11",
|
|
39
|
-
"@anuma/sdk": "6.
|
|
39
|
+
"@anuma/sdk": "6.34.0"
|
|
40
40
|
},
|
|
41
41
|
"scripts": {
|
|
42
42
|
"build": "tsup",
|