Sign in

pulls/pr_01m47d15m3e54sn21z27rpy5n9

public

pr_01m47d15m3e54sn21z27rpy5n9/packages/contracts/src/billing.ts

124 lines4,578 bytesCodeBlame

Pick any line to see why it is the way it is: the commit, the pull request and issue it came from, and what the agent was thinking.

Agents as a team: lifecycle, merge queue, billing and a new shell1import type { User, Viewer } from "./identity";
2import type { RepoPath } from "./repos";
3import type { Result } from "./result";
4
5/** Millionths of a US dollar in one dollar: the unit money is held in. */
6export const MICROS_PER_DOLLAR = 1_000_000;
7
8/** Whether workspaces are charged for agents at all, and with real money. */
9export type BillingStatus = {
10 /**
11 * False when no card processor is configured: nothing is charged, and who
12 * may run agents is decided some other way.
13 */
14 enabled: boolean;
15 /** False while the card processor is in its test mode, where cards are not real. */
16 live: boolean;
17};
18
19/** A workspace's standing. */
20export type BillingAccount = {
21 workspace: string;
22 /**
23 * Credit left, in millionths of a dollar. Can dip below zero by the cost
24 * of the runs that were under way when it ran out.
25 */
26 balanceMicros: number;
27 status: BillingStatus;
28 /** What is added to a run's cost, in percent. */
29 marginPercent: number;
Integrations: your own model provider, alerts that open issues, tickets agents read30 /** What a run on the workspace's own model provider is charged instead. */
31 orchestrationFeeMicros: number;
Agents as a team: lifecycle, merge queue, billing and a new shell32};
33
34/** One line of a workspace's statement. */
35export type LedgerEntry = {
36 id: string;
37 /** Credit bought with a card, or an agent's run. */
38 kind: "top_up" | "usage";
39 /** Positive for credit added, negative for usage. */
40 amountMicros: number;
41 description: string;
42 /** For usage: the repository and pull request the agent worked on. */
43 repo: string | null;
44 number: number | null;
45 /** For usage: `implement`, `review` or `update`. */
46 task: string | null;
47 /** For usage: the model, by its public name. */
48 model: string | null;
Integrations: your own model provider, alerts that open issues, tickets agents read49 /** For usage: who paid the model provider. */
50 billedTo: "g1t" | "workspace";
Agents as a team: lifecycle, merge queue, billing and a new shell51 /** For a top-up: the username of whoever paid. */
52 createdBy: string | null;
53 /** RFC 3339. */
54 createdAt: string;
55};
56
57/** What lets a sandbox, and nothing else, report what its run cost. */
58export type RunTicket = { runId: string; token: string };
59
60/**
61 * What agents cost, charged to the workspace they worked for. A workspace
62 * buys credit; each run deducts its cost plus g1t's margin; with no credit,
63 * no agent starts.
64 */
65export interface BillingApi {
66 status(): Promise<BillingStatus>;
67 /** Members of the workspace only. */
68 account(workspace: string, viewer: Viewer): Promise<Result<BillingAccount>>;
69 /** Newest first. Members of the workspace only. */
70 ledger(workspace: string, viewer: Viewer): Promise<Result<LedgerEntry[]>>;
Usage, like a hosting provider's: what agents cost, per day, task, repository and pull request71 /** What the workspace's agents cost since `since`, broken down. Members only. */
72 usage(workspace: string, viewer: Viewer, since: string): Promise<Result<Usage>>;
Agents as a team: lifecycle, merge queue, billing and a new shell73 /**
74 * Starts a card payment for credit and returns the page to send the
75 * person to. Owners only. The payment's id comes back to `returnUrl` as
76 * `session`.
77 */
78 checkout(actor: User, workspace: string, amountCents: number, returnUrl: string): Promise<Result<{ url: string }>>;
79 /** Credits a payment once the processor says it was made. Safe to repeat. */
80 confirm(workspace: string, viewer: Viewer, session: string): Promise<Result<BillingAccount>>;
81 /**
82 * Whether a workspace may start an agent now, asked before anything is
83 * opened for it. A failure, with the reason to show, when it has no credit.
84 */
85 canStart(workspace: string): Promise<Result<boolean>>;
86 /**
87 * Asks whether a workspace may start an agent and opens the run it will be
88 * charged for. Null when billing is off; a failure when there is no credit.
89 */
90 startRun(run: {
91 workspace: string;
92 repo: RepoPath;
93 number: number;
94 task: string;
95 model: string;
Integrations: your own model provider, alerts that open issues, tickets agents read96 /** `workspace` when the run uses the workspace's own model provider. */
97 billedTo?: "g1t" | "workspace";
Agents as a team: lifecycle, merge queue, billing and a new shell98 }): Promise<Result<RunTicket | null>>;
99}
Usage, like a hosting provider's: what agents cost, per day, task, repository and pull request100
101
102/** One slice of usage: what it was for, what it cost, how many runs. */
103export type UsageSlice = { key: string; micros: number; runs: number };
104
105/** What a workspace's agents cost over a period. */
106export type Usage = {
107 since: string;
108 /** Charged, including g1t's margin. */
109 spentMicros: number;
Integrations: your own model provider, alerts that open issues, tickets agents read110 /** What g1t's model provider charged, before the margin. */
Usage, like a hosting provider's: what agents cost, per day, task, repository and pull request111 costMicros: number;
Integrations: your own model provider, alerts that open issues, tickets agents read112 /** What runs on the workspace's own provider cost there, estimated. Not charged by g1t. */
113 providerMicros: number;
Usage, like a hosting provider's: what agents cost, per day, task, repository and pull request114 runs: number;
115 /** Spend per day and task, keyed `YYYY-MM-DD/task`. */
116 byDay: UsageSlice[];
117 byTask: UsageSlice[];
118 byRepo: UsageSlice[];
119 /** Keyed `namespace/name#number`. */
120 byPull: UsageSlice[];
121 byModel: UsageSlice[];
122 /** Credit bought in the period. */
123 addedMicros: number;
124};