@ottimis/jack-provider-sdk 0.2.0 → 0.4.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/backend.d.ts +8 -2
- package/dist/backend.d.ts.map +1 -1
- package/dist/cjs/index.js +1 -0
- package/dist/cjs/index.js.map +1 -1
- package/dist/cjs/usage.js +34 -0
- package/dist/cjs/usage.js.map +1 -0
- package/dist/index.d.ts +1 -0
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +1 -0
- package/dist/index.js.map +1 -1
- package/dist/provider.d.ts +35 -1
- package/dist/provider.d.ts.map +1 -1
- package/dist/usage.d.ts +219 -0
- package/dist/usage.d.ts.map +1 -0
- package/dist/usage.js +33 -0
- package/dist/usage.js.map +1 -0
- package/package.json +1 -1
- package/src/backend.ts +10 -1
- package/src/index.ts +1 -0
- package/src/provider.ts +35 -1
- package/src/usage.ts +228 -0
package/dist/backend.d.ts
CHANGED
|
@@ -33,8 +33,14 @@ import type { NormalizedMessage, NormalizedPermissionRequest, NormalizedPermissi
|
|
|
33
33
|
* list, so widening to `string` is required for non-Claude providers.
|
|
34
34
|
*/
|
|
35
35
|
export type BackendName = string;
|
|
36
|
-
/**
|
|
37
|
-
|
|
36
|
+
/**
|
|
37
|
+
* Permission gate behaviour. Open string union — providers declare which
|
|
38
|
+
* subset they support via {@link CapabilityMatrix.permissionModes}, and
|
|
39
|
+
* the host's permission-mode picker reads that catalog verbatim. Listed
|
|
40
|
+
* literals are the modes any in-tree provider has shipped to date;
|
|
41
|
+
* future providers may invent new strings without breaking the type.
|
|
42
|
+
*/
|
|
43
|
+
export type AgentPermissionMode = 'default' | 'acceptEdits' | 'plan' | 'auto' | 'bypassPermissions' | 'dontAsk' | (string & {});
|
|
38
44
|
/** Settings layers the provider should consult at boot. */
|
|
39
45
|
export type AgentSettingSource = 'user' | 'project' | 'local';
|
|
40
46
|
/**
|
package/dist/backend.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"backend.d.ts","sourceRoot":"","sources":["../src/backend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAA;AAC/C,OAAO,KAAK,EACV,iBAAiB,EACjB,2BAA2B,EAC3B,0BAA0B,EAC1B,mBAAmB,EACpB,MAAM,yBAAyB,CAAA;AAEhC;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,CAAA;AAMhC
|
|
1
|
+
{"version":3,"file":"backend.d.ts","sourceRoot":"","sources":["../src/backend.ts"],"names":[],"mappings":"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"}
|
package/dist/cjs/index.js
CHANGED
|
@@ -39,4 +39,5 @@ Object.defineProperty(exports, "__esModule", { value: true });
|
|
|
39
39
|
__exportStar(require("./backend"), exports);
|
|
40
40
|
__exportStar(require("./spawner"), exports);
|
|
41
41
|
__exportStar(require("./provider"), exports);
|
|
42
|
+
__exportStar(require("./usage"), exports);
|
|
42
43
|
//# sourceMappingURL=index.js.map
|
package/dist/cjs/index.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;;;;;;;;;;;;;;;;AAEH,4CAAyB;AACzB,4CAAyB;AACzB,6CAA0B"}
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;;;;;;;;;;;;;;;;AAEH,4CAAyB;AACzB,4CAAyB;AACzB,6CAA0B;AAC1B,0CAAuB"}
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
/**
|
|
3
|
+
* Usage / billing capability — provider-owned data flow.
|
|
4
|
+
*
|
|
5
|
+
* Each provider knows how to talk to its own billing surface (Claude
|
|
6
|
+
* cookie API for Pro/Max, OpenAI usage endpoints for Codex, Gemini's
|
|
7
|
+
* Google Cloud quotas, …) and how to map its SDK's per-message token
|
|
8
|
+
* counts into a canonical shape. The host runs a generic poll loop and
|
|
9
|
+
* a generic chip — it never special-cases any provider.
|
|
10
|
+
*
|
|
11
|
+
* Two surfaces:
|
|
12
|
+
*
|
|
13
|
+
* - `fetch()` for **account-level** snapshots. Pulled by a host poller
|
|
14
|
+
* on `recommendedPollIntervalSec` cadence (clamped to host bounds).
|
|
15
|
+
* What "account" means is provider-defined: Claude → org, Codex →
|
|
16
|
+
* OpenAI project, Gemini → Cloud Billing project.
|
|
17
|
+
*
|
|
18
|
+
* - `formatSessionMetrics()` for **per-session** translation. The
|
|
19
|
+
* manager already calls `backend.getContextUsage()` after every
|
|
20
|
+
* `assistant` message; that returns a loose `AgentContextUsage`
|
|
21
|
+
* bag. This hook lets the provider lift it into canonical
|
|
22
|
+
* {@link UsageMetric}[] without the host trying to interpret
|
|
23
|
+
* provider-specific fields.
|
|
24
|
+
*
|
|
25
|
+
* Single source of truth: the provider. Host plumbs, never decodes.
|
|
26
|
+
*
|
|
27
|
+
* Optional everywhere — providers without billing visibility (Codex
|
|
28
|
+
* without admin keys, Gemini without OAuth) leave `fetch()` returning
|
|
29
|
+
* an empty `metrics: []`. The capability flag stays `true` if the
|
|
30
|
+
* provider can format per-session metrics, `false` if it has nothing
|
|
31
|
+
* to say at all.
|
|
32
|
+
*/
|
|
33
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
34
|
+
//# sourceMappingURL=usage.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"usage.js","sourceRoot":"","sources":["../../src/usage.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG"}
|
package/dist/index.d.ts
CHANGED
|
@@ -23,6 +23,7 @@
|
|
|
23
23
|
export * from './backend';
|
|
24
24
|
export * from './spawner';
|
|
25
25
|
export * from './provider';
|
|
26
|
+
export * from './usage';
|
|
26
27
|
/**
|
|
27
28
|
* Re-export of `NormalizedMessage` from chat-core so consumers don't need
|
|
28
29
|
* to depend on it directly when their only entrypoint into the wire shape
|
package/dist/index.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,cAAc,WAAW,CAAA;AACzB,cAAc,WAAW,CAAA;AACzB,cAAc,YAAY,CAAA;
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,cAAc,WAAW,CAAA;AACzB,cAAc,WAAW,CAAA;AACzB,cAAc,YAAY,CAAA;AAC1B,cAAc,SAAS,CAAA;AAEvB;;;;;GAKG;AACH,YAAY,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAA"}
|
package/dist/index.js
CHANGED
package/dist/index.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,cAAc,WAAW,CAAA;AACzB,cAAc,WAAW,CAAA;AACzB,cAAc,YAAY,CAAA"}
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,cAAc,WAAW,CAAA;AACzB,cAAc,WAAW,CAAA;AACzB,cAAc,YAAY,CAAA;AAC1B,cAAc,SAAS,CAAA"}
|
package/dist/provider.d.ts
CHANGED
|
@@ -15,7 +15,8 @@
|
|
|
15
15
|
* This file is the boundary between Jack core and a provider package — keep
|
|
16
16
|
* it free of provider-specific imports.
|
|
17
17
|
*/
|
|
18
|
-
import type { AgentBackend, AgentQueryOptions, McpServerSpec } from './backend';
|
|
18
|
+
import type { AgentBackend, AgentPermissionMode, AgentQueryOptions, McpServerSpec } from './backend';
|
|
19
|
+
import type { UsageApi } from './usage';
|
|
19
20
|
import type { ZodType } from 'zod';
|
|
20
21
|
import type { ClientToolHandler, NormalizedMessage, NormalizedToolRef, ProviderUserContentPolicy, ToolShape } from '@ottimis/jack-chat-core';
|
|
21
22
|
export type ProviderId = string;
|
|
@@ -249,6 +250,31 @@ export type CapabilityMatrix = {
|
|
|
249
250
|
* renderer hides it and only shows the post-fact audit log.
|
|
250
251
|
*/
|
|
251
252
|
permissionGranularity: 'callback' | 'sandbox-only';
|
|
253
|
+
/**
|
|
254
|
+
* Provider exposes a usage / billing surface (account-level snapshot
|
|
255
|
+
* via `provider.usage.fetch()` and/or per-session metric translation
|
|
256
|
+
* via `formatSessionMetrics()`). When `false`, the chip hides the
|
|
257
|
+
* usage bars and no Connect affordance is offered.
|
|
258
|
+
*/
|
|
259
|
+
usage: boolean;
|
|
260
|
+
/**
|
|
261
|
+
* Permission modes the provider actually supports. Drives the
|
|
262
|
+
* Shift-Tab cycle in the renderer (`MessageInputBar`) and any
|
|
263
|
+
* provider-aware UI that picks a mode (settings, slash commands).
|
|
264
|
+
* Order matters — it's the cycle order on Shift-Tab.
|
|
265
|
+
*
|
|
266
|
+
* Each provider declares only the modes that have a meaningful
|
|
267
|
+
* behaviour for its runtime: Claude's `['default', 'acceptEdits',
|
|
268
|
+
* 'plan', 'auto']`, Codex's `['default', 'acceptEdits',
|
|
269
|
+
* 'bypassPermissions']` (no `'plan'` because there's no ExitPlanMode
|
|
270
|
+
* primitive — mapping `'plan'` to read-only sandbox would be
|
|
271
|
+
* misleading), Gemini's set inherited from ACP `available_modes`.
|
|
272
|
+
*
|
|
273
|
+
* Modes outside this list MAY still be accepted by
|
|
274
|
+
* `setPermissionMode()` (e.g. set programmatically via slash command
|
|
275
|
+
* or settings); the catalog only governs UI affordances.
|
|
276
|
+
*/
|
|
277
|
+
permissionModes: readonly AgentPermissionMode[];
|
|
252
278
|
};
|
|
253
279
|
/**
|
|
254
280
|
* Re-exports of canonical wire-shape types from chat-core so consumers of
|
|
@@ -588,6 +614,14 @@ export type JackProvider = {
|
|
|
588
614
|
* leave it undefined and the host returns empty snapshots.
|
|
589
615
|
*/
|
|
590
616
|
persistedPermissions?: PersistedPermissionsApi;
|
|
617
|
+
/**
|
|
618
|
+
* Usage / billing capability — provider-owned data flow. See
|
|
619
|
+
* {@link UsageApi}. Optional; when undefined the chip degrades to
|
|
620
|
+
* showing nothing (and `capabilities.usage` MUST be `false`). The
|
|
621
|
+
* provider stays the single source of truth: host plumbs, never
|
|
622
|
+
* decodes.
|
|
623
|
+
*/
|
|
624
|
+
usage?: UsageApi;
|
|
591
625
|
};
|
|
592
626
|
/**
|
|
593
627
|
* Provider-neutral spec for an in-process MCP server the host wants to
|
package/dist/provider.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,WAAW,CAAA;
|
|
1
|
+
{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"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"}
|
package/dist/usage.d.ts
ADDED
|
@@ -0,0 +1,219 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Usage / billing capability — provider-owned data flow.
|
|
3
|
+
*
|
|
4
|
+
* Each provider knows how to talk to its own billing surface (Claude
|
|
5
|
+
* cookie API for Pro/Max, OpenAI usage endpoints for Codex, Gemini's
|
|
6
|
+
* Google Cloud quotas, …) and how to map its SDK's per-message token
|
|
7
|
+
* counts into a canonical shape. The host runs a generic poll loop and
|
|
8
|
+
* a generic chip — it never special-cases any provider.
|
|
9
|
+
*
|
|
10
|
+
* Two surfaces:
|
|
11
|
+
*
|
|
12
|
+
* - `fetch()` for **account-level** snapshots. Pulled by a host poller
|
|
13
|
+
* on `recommendedPollIntervalSec` cadence (clamped to host bounds).
|
|
14
|
+
* What "account" means is provider-defined: Claude → org, Codex →
|
|
15
|
+
* OpenAI project, Gemini → Cloud Billing project.
|
|
16
|
+
*
|
|
17
|
+
* - `formatSessionMetrics()` for **per-session** translation. The
|
|
18
|
+
* manager already calls `backend.getContextUsage()` after every
|
|
19
|
+
* `assistant` message; that returns a loose `AgentContextUsage`
|
|
20
|
+
* bag. This hook lets the provider lift it into canonical
|
|
21
|
+
* {@link UsageMetric}[] without the host trying to interpret
|
|
22
|
+
* provider-specific fields.
|
|
23
|
+
*
|
|
24
|
+
* Single source of truth: the provider. Host plumbs, never decodes.
|
|
25
|
+
*
|
|
26
|
+
* Optional everywhere — providers without billing visibility (Codex
|
|
27
|
+
* without admin keys, Gemini without OAuth) leave `fetch()` returning
|
|
28
|
+
* an empty `metrics: []`. The capability flag stays `true` if the
|
|
29
|
+
* provider can format per-session metrics, `false` if it has nothing
|
|
30
|
+
* to say at all.
|
|
31
|
+
*/
|
|
32
|
+
import type { AgentContextUsage } from './backend';
|
|
33
|
+
/**
|
|
34
|
+
* Canonical metric kinds. New kinds extend this union additively when a
|
|
35
|
+
* provider has a meaningfully different shape (e.g. a future
|
|
36
|
+
* `quarterly_burn` for enterprise billing). Adding a kind is a minor
|
|
37
|
+
* SDK bump; the renderer's dispatch table grows alongside.
|
|
38
|
+
*/
|
|
39
|
+
export type UsageMetric = TimeWindowMetric | TokenUtilizationMetric | MonthlySpendMetric;
|
|
40
|
+
/**
|
|
41
|
+
* Rolling-window utilization. The classic Claude Pro/Max bucket
|
|
42
|
+
* (5-hour, 7-day) — utilization 0..1 with a hard reset boundary.
|
|
43
|
+
*
|
|
44
|
+
* Optional `used` / `limit` / `unit` carry raw counts when the
|
|
45
|
+
* provider exposes them (Gemini free-tier daily quota: 12 of 50
|
|
46
|
+
* requests). Claude's cookie API gives only `utilization`, so those
|
|
47
|
+
* stay undefined and the chip falls back to "X% of N-hour usage".
|
|
48
|
+
*/
|
|
49
|
+
export type TimeWindowMetric = {
|
|
50
|
+
kind: 'time_window';
|
|
51
|
+
/** Stable, provider-defined key. e.g. `'five_hour'`, `'seven_day_opus'`, `'daily'`. */
|
|
52
|
+
id: string;
|
|
53
|
+
/** Human-readable label for UI. Provider supplies (i18n is its concern). */
|
|
54
|
+
label: string;
|
|
55
|
+
/** Window utilization in [0, 1]. */
|
|
56
|
+
utilization: number;
|
|
57
|
+
/** Optional: raw count consumed in the window (when known). */
|
|
58
|
+
used?: number;
|
|
59
|
+
/** Optional: raw cap of the window (when known). */
|
|
60
|
+
limit?: number;
|
|
61
|
+
/** Optional: unit of `used`/`limit`. Default `'tokens'`. Chip uses for formatting. */
|
|
62
|
+
unit?: 'tokens' | 'requests' | (string & {});
|
|
63
|
+
/** ISO 8601 timestamp when the window resets. */
|
|
64
|
+
resetsAt: string;
|
|
65
|
+
/** Window length in seconds. Used for elapsed-progress UI. */
|
|
66
|
+
windowSeconds: number;
|
|
67
|
+
};
|
|
68
|
+
/**
|
|
69
|
+
* Count-based utilization without a time boundary. Used for context
|
|
70
|
+
* window pressure ("X tokens of Y max") and any cumulative provider
|
|
71
|
+
* metric that doesn't reset on a clock (lifetime / billing-period
|
|
72
|
+
* tokens, etc).
|
|
73
|
+
*
|
|
74
|
+
* `max` is optional — a provider tracking total token consumption
|
|
75
|
+
* without a hard cap (analytics, not gating) leaves it undefined and
|
|
76
|
+
* the chip shows just the count.
|
|
77
|
+
*/
|
|
78
|
+
export type TokenUtilizationMetric = {
|
|
79
|
+
kind: 'token_utilization';
|
|
80
|
+
/** Stable, provider-defined key. e.g. `'context'`, `'session_total'`. */
|
|
81
|
+
id: string;
|
|
82
|
+
/** Human-readable label for UI. */
|
|
83
|
+
label: string;
|
|
84
|
+
/** Tokens consumed. */
|
|
85
|
+
used: number;
|
|
86
|
+
/** Optional cap. Undefined = no cap, chip hides the ratio. */
|
|
87
|
+
max?: number;
|
|
88
|
+
};
|
|
89
|
+
/**
|
|
90
|
+
* Spend on a billing cycle (typically monthly). Only meaningful for
|
|
91
|
+
* providers using API-key auth — subscription users have rolling-window
|
|
92
|
+
* quotas, not $-spend.
|
|
93
|
+
*
|
|
94
|
+
* `budgetUsd` is optional: most users don't set a budget, so the chip
|
|
95
|
+
* shows raw spend without a denominator. When present, chip can render
|
|
96
|
+
* a budget bar.
|
|
97
|
+
*/
|
|
98
|
+
export type MonthlySpendMetric = {
|
|
99
|
+
kind: 'monthly_spend';
|
|
100
|
+
id: string;
|
|
101
|
+
/** Cycle label, e.g. "May 2026" or "Current cycle". */
|
|
102
|
+
label: string;
|
|
103
|
+
spentUsd: number;
|
|
104
|
+
budgetUsd?: number;
|
|
105
|
+
/** ISO 8601 — start of the billing cycle. */
|
|
106
|
+
cycleStart: string;
|
|
107
|
+
/** ISO 8601 — end of the billing cycle. */
|
|
108
|
+
cycleEnd: string;
|
|
109
|
+
};
|
|
110
|
+
/**
|
|
111
|
+
* One snapshot of provider-side usage data, as returned by
|
|
112
|
+
* {@link UsageApi.fetch}. `metrics` may be empty when the provider has
|
|
113
|
+
* no account-level data to report (Codex without billing key, etc.).
|
|
114
|
+
*/
|
|
115
|
+
export type UsageSnapshot = {
|
|
116
|
+
metrics: UsageMetric[];
|
|
117
|
+
/** ISO 8601 — when this snapshot was observed. */
|
|
118
|
+
observedAt: string;
|
|
119
|
+
/** Verbatim provider payload, kept for debug / future analytics.
|
|
120
|
+
* Never consumed by host or chip directly. */
|
|
121
|
+
raw?: unknown;
|
|
122
|
+
};
|
|
123
|
+
/**
|
|
124
|
+
* Connection / authorization state of the provider's usage surface.
|
|
125
|
+
* Surface in the chip's pop-over so the user knows whether they're
|
|
126
|
+
* tracking real numbers or seeing a cached / disconnected snapshot.
|
|
127
|
+
*/
|
|
128
|
+
export type UsageStatus = {
|
|
129
|
+
connected: boolean;
|
|
130
|
+
/** Optional human-readable identity (org name, email, project id). */
|
|
131
|
+
identity?: string;
|
|
132
|
+
/**
|
|
133
|
+
* Provider-defined auth-mode hint. Lets the renderer adapt copy
|
|
134
|
+
* (e.g. "Connected as API user" vs "Pro subscription"). Stable
|
|
135
|
+
* provider-supplied strings; host doesn't interpret beyond
|
|
136
|
+
* passthrough.
|
|
137
|
+
*/
|
|
138
|
+
authMode?: 'subscription' | 'api_key' | (string & {});
|
|
139
|
+
/** Last error message, when not connected. */
|
|
140
|
+
error?: string;
|
|
141
|
+
};
|
|
142
|
+
/**
|
|
143
|
+
* Result of {@link UsageApi.connect}. The `'choose'` branch covers
|
|
144
|
+
* multi-org / multi-project accounts where the user must pick one
|
|
145
|
+
* (Claude's multi-org case). Generalising to a generic option list
|
|
146
|
+
* means the chip's UI doesn't special-case any provider.
|
|
147
|
+
*/
|
|
148
|
+
export type UsageConnectResult = {
|
|
149
|
+
kind: 'ready';
|
|
150
|
+
identity: string;
|
|
151
|
+
} | {
|
|
152
|
+
kind: 'choose';
|
|
153
|
+
options: UsageConnectOption[];
|
|
154
|
+
} | {
|
|
155
|
+
kind: 'error';
|
|
156
|
+
error: string;
|
|
157
|
+
} | {
|
|
158
|
+
kind: 'cancelled';
|
|
159
|
+
};
|
|
160
|
+
export type UsageConnectOption = {
|
|
161
|
+
id: string;
|
|
162
|
+
label: string;
|
|
163
|
+
};
|
|
164
|
+
/**
|
|
165
|
+
* Context handed to {@link UsageApi.connect}. Currently just a parent
|
|
166
|
+
* window for Electron-coupled flows (Claude opens a child BrowserWindow
|
|
167
|
+
* on `claude.ai/login`). Typed as `unknown` here so the SDK doesn't
|
|
168
|
+
* pull in `electron` as a peer dep — the host narrows to
|
|
169
|
+
* `BrowserWindow` at the call site.
|
|
170
|
+
*/
|
|
171
|
+
export type UsageConnectContext = {
|
|
172
|
+
/** Parent window for any modal flow the provider needs to open. */
|
|
173
|
+
parentWindow?: unknown;
|
|
174
|
+
};
|
|
175
|
+
/**
|
|
176
|
+
* Provider-owned usage capability. Optional on {@link JackProvider};
|
|
177
|
+
* absent = host hides the chip's "Connect" affordance and the
|
|
178
|
+
* capability flag is `false`.
|
|
179
|
+
*/
|
|
180
|
+
export type UsageApi = {
|
|
181
|
+
/** Current connection state — used for chip display + gating. */
|
|
182
|
+
status(): Promise<UsageStatus>;
|
|
183
|
+
/**
|
|
184
|
+
* Open the provider's connect flow. Whatever modality the provider
|
|
185
|
+
* needs (login window, API-key picker, OAuth redirect) lives here.
|
|
186
|
+
*/
|
|
187
|
+
connect(ctx: UsageConnectContext): Promise<UsageConnectResult>;
|
|
188
|
+
/**
|
|
189
|
+
* When `connect()` returned `'choose'`, host calls this with the
|
|
190
|
+
* user's pick. Optional — providers that never choose omit it.
|
|
191
|
+
*/
|
|
192
|
+
selectOption?(optionId: string): Promise<UsageConnectResult>;
|
|
193
|
+
/** Drop credentials and stop any provider-side polling. */
|
|
194
|
+
disconnect(): Promise<void>;
|
|
195
|
+
/**
|
|
196
|
+
* Fetch one fresh account-level snapshot. Empty `metrics: []` is
|
|
197
|
+
* fine when the provider has no billing surface yet — the capability
|
|
198
|
+
* stays `true` for the per-session bridge.
|
|
199
|
+
*/
|
|
200
|
+
fetch(): Promise<UsageSnapshot>;
|
|
201
|
+
/**
|
|
202
|
+
* Recommended poll cadence (seconds). Host clamps to its bounds.
|
|
203
|
+
* Optional — host falls back to its own default if unset.
|
|
204
|
+
*/
|
|
205
|
+
recommendedPollIntervalSec?: number;
|
|
206
|
+
/**
|
|
207
|
+
* Translate the loose {@link AgentContextUsage} the manager pulls from
|
|
208
|
+
* `backend.getContextUsage()` into canonical {@link UsageMetric}[].
|
|
209
|
+
*
|
|
210
|
+
* Pure function (no side effects) — provider knows its own SDK's
|
|
211
|
+
* shape and lifts it. Empty array OK when the raw bag has nothing
|
|
212
|
+
* useful (e.g. fresh session before any message lands).
|
|
213
|
+
*
|
|
214
|
+
* Optional. Providers without per-session token visibility omit it
|
|
215
|
+
* and the chip skips the per-session row.
|
|
216
|
+
*/
|
|
217
|
+
formatSessionMetrics?(raw: AgentContextUsage): UsageMetric[];
|
|
218
|
+
};
|
|
219
|
+
//# sourceMappingURL=usage.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"usage.d.ts","sourceRoot":"","sources":["../src/usage.ts"],"names":[],"mappings":"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"}
|
package/dist/usage.js
ADDED
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Usage / billing capability — provider-owned data flow.
|
|
3
|
+
*
|
|
4
|
+
* Each provider knows how to talk to its own billing surface (Claude
|
|
5
|
+
* cookie API for Pro/Max, OpenAI usage endpoints for Codex, Gemini's
|
|
6
|
+
* Google Cloud quotas, …) and how to map its SDK's per-message token
|
|
7
|
+
* counts into a canonical shape. The host runs a generic poll loop and
|
|
8
|
+
* a generic chip — it never special-cases any provider.
|
|
9
|
+
*
|
|
10
|
+
* Two surfaces:
|
|
11
|
+
*
|
|
12
|
+
* - `fetch()` for **account-level** snapshots. Pulled by a host poller
|
|
13
|
+
* on `recommendedPollIntervalSec` cadence (clamped to host bounds).
|
|
14
|
+
* What "account" means is provider-defined: Claude → org, Codex →
|
|
15
|
+
* OpenAI project, Gemini → Cloud Billing project.
|
|
16
|
+
*
|
|
17
|
+
* - `formatSessionMetrics()` for **per-session** translation. The
|
|
18
|
+
* manager already calls `backend.getContextUsage()` after every
|
|
19
|
+
* `assistant` message; that returns a loose `AgentContextUsage`
|
|
20
|
+
* bag. This hook lets the provider lift it into canonical
|
|
21
|
+
* {@link UsageMetric}[] without the host trying to interpret
|
|
22
|
+
* provider-specific fields.
|
|
23
|
+
*
|
|
24
|
+
* Single source of truth: the provider. Host plumbs, never decodes.
|
|
25
|
+
*
|
|
26
|
+
* Optional everywhere — providers without billing visibility (Codex
|
|
27
|
+
* without admin keys, Gemini without OAuth) leave `fetch()` returning
|
|
28
|
+
* an empty `metrics: []`. The capability flag stays `true` if the
|
|
29
|
+
* provider can format per-session metrics, `false` if it has nothing
|
|
30
|
+
* to say at all.
|
|
31
|
+
*/
|
|
32
|
+
export {};
|
|
33
|
+
//# sourceMappingURL=usage.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"usage.js","sourceRoot":"","sources":["../src/usage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG"}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@ottimis/jack-provider-sdk",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.4.0",
|
|
4
4
|
"description": "Plugin contract for AI provider integrations in Jack — backend interface, capability matrix, spawner primitives, knowledge context. Consumed both by in-tree providers and external packages.",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"repository": {
|
package/src/backend.ts
CHANGED
|
@@ -45,12 +45,21 @@ export type BackendName = string
|
|
|
45
45
|
// Neutral option types
|
|
46
46
|
// ─────────────────────────────────────────────────────────────────────────────
|
|
47
47
|
|
|
48
|
-
/**
|
|
48
|
+
/**
|
|
49
|
+
* Permission gate behaviour. Open string union — providers declare which
|
|
50
|
+
* subset they support via {@link CapabilityMatrix.permissionModes}, and
|
|
51
|
+
* the host's permission-mode picker reads that catalog verbatim. Listed
|
|
52
|
+
* literals are the modes any in-tree provider has shipped to date;
|
|
53
|
+
* future providers may invent new strings without breaking the type.
|
|
54
|
+
*/
|
|
49
55
|
export type AgentPermissionMode =
|
|
50
56
|
| 'default'
|
|
51
57
|
| 'acceptEdits'
|
|
52
58
|
| 'plan'
|
|
59
|
+
| 'auto'
|
|
53
60
|
| 'bypassPermissions'
|
|
61
|
+
| 'dontAsk'
|
|
62
|
+
| (string & {})
|
|
54
63
|
|
|
55
64
|
/** Settings layers the provider should consult at boot. */
|
|
56
65
|
export type AgentSettingSource = 'user' | 'project' | 'local'
|
package/src/index.ts
CHANGED
package/src/provider.ts
CHANGED
|
@@ -16,7 +16,8 @@
|
|
|
16
16
|
* it free of provider-specific imports.
|
|
17
17
|
*/
|
|
18
18
|
|
|
19
|
-
import type { AgentBackend, AgentQueryOptions, McpServerSpec } from './backend'
|
|
19
|
+
import type { AgentBackend, AgentPermissionMode, AgentQueryOptions, McpServerSpec } from './backend'
|
|
20
|
+
import type { UsageApi } from './usage'
|
|
20
21
|
import type { ZodType } from 'zod'
|
|
21
22
|
import type {
|
|
22
23
|
ClientToolHandler,
|
|
@@ -265,6 +266,31 @@ export type CapabilityMatrix = {
|
|
|
265
266
|
* renderer hides it and only shows the post-fact audit log.
|
|
266
267
|
*/
|
|
267
268
|
permissionGranularity: 'callback' | 'sandbox-only'
|
|
269
|
+
/**
|
|
270
|
+
* Provider exposes a usage / billing surface (account-level snapshot
|
|
271
|
+
* via `provider.usage.fetch()` and/or per-session metric translation
|
|
272
|
+
* via `formatSessionMetrics()`). When `false`, the chip hides the
|
|
273
|
+
* usage bars and no Connect affordance is offered.
|
|
274
|
+
*/
|
|
275
|
+
usage: boolean
|
|
276
|
+
/**
|
|
277
|
+
* Permission modes the provider actually supports. Drives the
|
|
278
|
+
* Shift-Tab cycle in the renderer (`MessageInputBar`) and any
|
|
279
|
+
* provider-aware UI that picks a mode (settings, slash commands).
|
|
280
|
+
* Order matters — it's the cycle order on Shift-Tab.
|
|
281
|
+
*
|
|
282
|
+
* Each provider declares only the modes that have a meaningful
|
|
283
|
+
* behaviour for its runtime: Claude's `['default', 'acceptEdits',
|
|
284
|
+
* 'plan', 'auto']`, Codex's `['default', 'acceptEdits',
|
|
285
|
+
* 'bypassPermissions']` (no `'plan'` because there's no ExitPlanMode
|
|
286
|
+
* primitive — mapping `'plan'` to read-only sandbox would be
|
|
287
|
+
* misleading), Gemini's set inherited from ACP `available_modes`.
|
|
288
|
+
*
|
|
289
|
+
* Modes outside this list MAY still be accepted by
|
|
290
|
+
* `setPermissionMode()` (e.g. set programmatically via slash command
|
|
291
|
+
* or settings); the catalog only governs UI affordances.
|
|
292
|
+
*/
|
|
293
|
+
permissionModes: readonly AgentPermissionMode[]
|
|
268
294
|
}
|
|
269
295
|
|
|
270
296
|
/**
|
|
@@ -642,6 +668,14 @@ export type JackProvider = {
|
|
|
642
668
|
* leave it undefined and the host returns empty snapshots.
|
|
643
669
|
*/
|
|
644
670
|
persistedPermissions?: PersistedPermissionsApi
|
|
671
|
+
/**
|
|
672
|
+
* Usage / billing capability — provider-owned data flow. See
|
|
673
|
+
* {@link UsageApi}. Optional; when undefined the chip degrades to
|
|
674
|
+
* showing nothing (and `capabilities.usage` MUST be `false`). The
|
|
675
|
+
* provider stays the single source of truth: host plumbs, never
|
|
676
|
+
* decodes.
|
|
677
|
+
*/
|
|
678
|
+
usage?: UsageApi
|
|
645
679
|
}
|
|
646
680
|
|
|
647
681
|
/**
|
package/src/usage.ts
ADDED
|
@@ -0,0 +1,228 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Usage / billing capability — provider-owned data flow.
|
|
3
|
+
*
|
|
4
|
+
* Each provider knows how to talk to its own billing surface (Claude
|
|
5
|
+
* cookie API for Pro/Max, OpenAI usage endpoints for Codex, Gemini's
|
|
6
|
+
* Google Cloud quotas, …) and how to map its SDK's per-message token
|
|
7
|
+
* counts into a canonical shape. The host runs a generic poll loop and
|
|
8
|
+
* a generic chip — it never special-cases any provider.
|
|
9
|
+
*
|
|
10
|
+
* Two surfaces:
|
|
11
|
+
*
|
|
12
|
+
* - `fetch()` for **account-level** snapshots. Pulled by a host poller
|
|
13
|
+
* on `recommendedPollIntervalSec` cadence (clamped to host bounds).
|
|
14
|
+
* What "account" means is provider-defined: Claude → org, Codex →
|
|
15
|
+
* OpenAI project, Gemini → Cloud Billing project.
|
|
16
|
+
*
|
|
17
|
+
* - `formatSessionMetrics()` for **per-session** translation. The
|
|
18
|
+
* manager already calls `backend.getContextUsage()` after every
|
|
19
|
+
* `assistant` message; that returns a loose `AgentContextUsage`
|
|
20
|
+
* bag. This hook lets the provider lift it into canonical
|
|
21
|
+
* {@link UsageMetric}[] without the host trying to interpret
|
|
22
|
+
* provider-specific fields.
|
|
23
|
+
*
|
|
24
|
+
* Single source of truth: the provider. Host plumbs, never decodes.
|
|
25
|
+
*
|
|
26
|
+
* Optional everywhere — providers without billing visibility (Codex
|
|
27
|
+
* without admin keys, Gemini without OAuth) leave `fetch()` returning
|
|
28
|
+
* an empty `metrics: []`. The capability flag stays `true` if the
|
|
29
|
+
* provider can format per-session metrics, `false` if it has nothing
|
|
30
|
+
* to say at all.
|
|
31
|
+
*/
|
|
32
|
+
|
|
33
|
+
import type { AgentContextUsage } from './backend'
|
|
34
|
+
|
|
35
|
+
/**
|
|
36
|
+
* Canonical metric kinds. New kinds extend this union additively when a
|
|
37
|
+
* provider has a meaningfully different shape (e.g. a future
|
|
38
|
+
* `quarterly_burn` for enterprise billing). Adding a kind is a minor
|
|
39
|
+
* SDK bump; the renderer's dispatch table grows alongside.
|
|
40
|
+
*/
|
|
41
|
+
export type UsageMetric = TimeWindowMetric | TokenUtilizationMetric | MonthlySpendMetric
|
|
42
|
+
|
|
43
|
+
/**
|
|
44
|
+
* Rolling-window utilization. The classic Claude Pro/Max bucket
|
|
45
|
+
* (5-hour, 7-day) — utilization 0..1 with a hard reset boundary.
|
|
46
|
+
*
|
|
47
|
+
* Optional `used` / `limit` / `unit` carry raw counts when the
|
|
48
|
+
* provider exposes them (Gemini free-tier daily quota: 12 of 50
|
|
49
|
+
* requests). Claude's cookie API gives only `utilization`, so those
|
|
50
|
+
* stay undefined and the chip falls back to "X% of N-hour usage".
|
|
51
|
+
*/
|
|
52
|
+
export type TimeWindowMetric = {
|
|
53
|
+
kind: 'time_window'
|
|
54
|
+
/** Stable, provider-defined key. e.g. `'five_hour'`, `'seven_day_opus'`, `'daily'`. */
|
|
55
|
+
id: string
|
|
56
|
+
/** Human-readable label for UI. Provider supplies (i18n is its concern). */
|
|
57
|
+
label: string
|
|
58
|
+
/** Window utilization in [0, 1]. */
|
|
59
|
+
utilization: number
|
|
60
|
+
/** Optional: raw count consumed in the window (when known). */
|
|
61
|
+
used?: number
|
|
62
|
+
/** Optional: raw cap of the window (when known). */
|
|
63
|
+
limit?: number
|
|
64
|
+
/** Optional: unit of `used`/`limit`. Default `'tokens'`. Chip uses for formatting. */
|
|
65
|
+
unit?: 'tokens' | 'requests' | (string & {})
|
|
66
|
+
/** ISO 8601 timestamp when the window resets. */
|
|
67
|
+
resetsAt: string
|
|
68
|
+
/** Window length in seconds. Used for elapsed-progress UI. */
|
|
69
|
+
windowSeconds: number
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
/**
|
|
73
|
+
* Count-based utilization without a time boundary. Used for context
|
|
74
|
+
* window pressure ("X tokens of Y max") and any cumulative provider
|
|
75
|
+
* metric that doesn't reset on a clock (lifetime / billing-period
|
|
76
|
+
* tokens, etc).
|
|
77
|
+
*
|
|
78
|
+
* `max` is optional — a provider tracking total token consumption
|
|
79
|
+
* without a hard cap (analytics, not gating) leaves it undefined and
|
|
80
|
+
* the chip shows just the count.
|
|
81
|
+
*/
|
|
82
|
+
export type TokenUtilizationMetric = {
|
|
83
|
+
kind: 'token_utilization'
|
|
84
|
+
/** Stable, provider-defined key. e.g. `'context'`, `'session_total'`. */
|
|
85
|
+
id: string
|
|
86
|
+
/** Human-readable label for UI. */
|
|
87
|
+
label: string
|
|
88
|
+
/** Tokens consumed. */
|
|
89
|
+
used: number
|
|
90
|
+
/** Optional cap. Undefined = no cap, chip hides the ratio. */
|
|
91
|
+
max?: number
|
|
92
|
+
}
|
|
93
|
+
|
|
94
|
+
/**
|
|
95
|
+
* Spend on a billing cycle (typically monthly). Only meaningful for
|
|
96
|
+
* providers using API-key auth — subscription users have rolling-window
|
|
97
|
+
* quotas, not $-spend.
|
|
98
|
+
*
|
|
99
|
+
* `budgetUsd` is optional: most users don't set a budget, so the chip
|
|
100
|
+
* shows raw spend without a denominator. When present, chip can render
|
|
101
|
+
* a budget bar.
|
|
102
|
+
*/
|
|
103
|
+
export type MonthlySpendMetric = {
|
|
104
|
+
kind: 'monthly_spend'
|
|
105
|
+
id: string
|
|
106
|
+
/** Cycle label, e.g. "May 2026" or "Current cycle". */
|
|
107
|
+
label: string
|
|
108
|
+
spentUsd: number
|
|
109
|
+
budgetUsd?: number
|
|
110
|
+
/** ISO 8601 — start of the billing cycle. */
|
|
111
|
+
cycleStart: string
|
|
112
|
+
/** ISO 8601 — end of the billing cycle. */
|
|
113
|
+
cycleEnd: string
|
|
114
|
+
}
|
|
115
|
+
|
|
116
|
+
/**
|
|
117
|
+
* One snapshot of provider-side usage data, as returned by
|
|
118
|
+
* {@link UsageApi.fetch}. `metrics` may be empty when the provider has
|
|
119
|
+
* no account-level data to report (Codex without billing key, etc.).
|
|
120
|
+
*/
|
|
121
|
+
export type UsageSnapshot = {
|
|
122
|
+
metrics: UsageMetric[]
|
|
123
|
+
/** ISO 8601 — when this snapshot was observed. */
|
|
124
|
+
observedAt: string
|
|
125
|
+
/** Verbatim provider payload, kept for debug / future analytics.
|
|
126
|
+
* Never consumed by host or chip directly. */
|
|
127
|
+
raw?: unknown
|
|
128
|
+
}
|
|
129
|
+
|
|
130
|
+
/**
|
|
131
|
+
* Connection / authorization state of the provider's usage surface.
|
|
132
|
+
* Surface in the chip's pop-over so the user knows whether they're
|
|
133
|
+
* tracking real numbers or seeing a cached / disconnected snapshot.
|
|
134
|
+
*/
|
|
135
|
+
export type UsageStatus = {
|
|
136
|
+
connected: boolean
|
|
137
|
+
/** Optional human-readable identity (org name, email, project id). */
|
|
138
|
+
identity?: string
|
|
139
|
+
/**
|
|
140
|
+
* Provider-defined auth-mode hint. Lets the renderer adapt copy
|
|
141
|
+
* (e.g. "Connected as API user" vs "Pro subscription"). Stable
|
|
142
|
+
* provider-supplied strings; host doesn't interpret beyond
|
|
143
|
+
* passthrough.
|
|
144
|
+
*/
|
|
145
|
+
authMode?: 'subscription' | 'api_key' | (string & {})
|
|
146
|
+
/** Last error message, when not connected. */
|
|
147
|
+
error?: string
|
|
148
|
+
}
|
|
149
|
+
|
|
150
|
+
/**
|
|
151
|
+
* Result of {@link UsageApi.connect}. The `'choose'` branch covers
|
|
152
|
+
* multi-org / multi-project accounts where the user must pick one
|
|
153
|
+
* (Claude's multi-org case). Generalising to a generic option list
|
|
154
|
+
* means the chip's UI doesn't special-case any provider.
|
|
155
|
+
*/
|
|
156
|
+
export type UsageConnectResult =
|
|
157
|
+
| { kind: 'ready'; identity: string }
|
|
158
|
+
| { kind: 'choose'; options: UsageConnectOption[] }
|
|
159
|
+
| { kind: 'error'; error: string }
|
|
160
|
+
| { kind: 'cancelled' }
|
|
161
|
+
|
|
162
|
+
export type UsageConnectOption = {
|
|
163
|
+
id: string
|
|
164
|
+
label: string
|
|
165
|
+
}
|
|
166
|
+
|
|
167
|
+
/**
|
|
168
|
+
* Context handed to {@link UsageApi.connect}. Currently just a parent
|
|
169
|
+
* window for Electron-coupled flows (Claude opens a child BrowserWindow
|
|
170
|
+
* on `claude.ai/login`). Typed as `unknown` here so the SDK doesn't
|
|
171
|
+
* pull in `electron` as a peer dep — the host narrows to
|
|
172
|
+
* `BrowserWindow` at the call site.
|
|
173
|
+
*/
|
|
174
|
+
export type UsageConnectContext = {
|
|
175
|
+
/** Parent window for any modal flow the provider needs to open. */
|
|
176
|
+
parentWindow?: unknown
|
|
177
|
+
}
|
|
178
|
+
|
|
179
|
+
/**
|
|
180
|
+
* Provider-owned usage capability. Optional on {@link JackProvider};
|
|
181
|
+
* absent = host hides the chip's "Connect" affordance and the
|
|
182
|
+
* capability flag is `false`.
|
|
183
|
+
*/
|
|
184
|
+
export type UsageApi = {
|
|
185
|
+
/** Current connection state — used for chip display + gating. */
|
|
186
|
+
status(): Promise<UsageStatus>
|
|
187
|
+
|
|
188
|
+
/**
|
|
189
|
+
* Open the provider's connect flow. Whatever modality the provider
|
|
190
|
+
* needs (login window, API-key picker, OAuth redirect) lives here.
|
|
191
|
+
*/
|
|
192
|
+
connect(ctx: UsageConnectContext): Promise<UsageConnectResult>
|
|
193
|
+
|
|
194
|
+
/**
|
|
195
|
+
* When `connect()` returned `'choose'`, host calls this with the
|
|
196
|
+
* user's pick. Optional — providers that never choose omit it.
|
|
197
|
+
*/
|
|
198
|
+
selectOption?(optionId: string): Promise<UsageConnectResult>
|
|
199
|
+
|
|
200
|
+
/** Drop credentials and stop any provider-side polling. */
|
|
201
|
+
disconnect(): Promise<void>
|
|
202
|
+
|
|
203
|
+
/**
|
|
204
|
+
* Fetch one fresh account-level snapshot. Empty `metrics: []` is
|
|
205
|
+
* fine when the provider has no billing surface yet — the capability
|
|
206
|
+
* stays `true` for the per-session bridge.
|
|
207
|
+
*/
|
|
208
|
+
fetch(): Promise<UsageSnapshot>
|
|
209
|
+
|
|
210
|
+
/**
|
|
211
|
+
* Recommended poll cadence (seconds). Host clamps to its bounds.
|
|
212
|
+
* Optional — host falls back to its own default if unset.
|
|
213
|
+
*/
|
|
214
|
+
recommendedPollIntervalSec?: number
|
|
215
|
+
|
|
216
|
+
/**
|
|
217
|
+
* Translate the loose {@link AgentContextUsage} the manager pulls from
|
|
218
|
+
* `backend.getContextUsage()` into canonical {@link UsageMetric}[].
|
|
219
|
+
*
|
|
220
|
+
* Pure function (no side effects) — provider knows its own SDK's
|
|
221
|
+
* shape and lifts it. Empty array OK when the raw bag has nothing
|
|
222
|
+
* useful (e.g. fresh session before any message lands).
|
|
223
|
+
*
|
|
224
|
+
* Optional. Providers without per-session token visibility omit it
|
|
225
|
+
* and the chip skips the per-session row.
|
|
226
|
+
*/
|
|
227
|
+
formatSessionMetrics?(raw: AgentContextUsage): UsageMetric[]
|
|
228
|
+
}
|