@noimosai/platform-cli 0.1.3 → 0.1.4

package/dist/schema/platformCustomTools.js

@@ -0,0 +1,148 @@
+import { z } from "zod";
+import { projectScopeSchema, platformJsonObjectSchema, PLATFORM_SANDBOX_LIMITS } from "./platformPublicExecution.js";
+import { isPlatformCallerHeaderName, isPlatformHeaderValue, PLATFORM_APP_HOST_PATTERN, PLATFORM_APP_RESERVED_HEADERS } from "./platformHttpConstraints.js";
+import { platformTeamSecretNameSchema } from "./platformTeamSecretName.js";
+export const PLATFORM_CUSTOM_TOOL_PREFIX = "custom__";
+export const PLATFORM_CUSTOM_TOOL_LIMITS = {
+    perProject: 100,
+    versions: 50,
+    slugChars: 40,
+    titleChars: 80,
+    descriptionChars: 1_000,
+    codeChars: 40_000,
+    schemaBytes: 16_384,
+    inputBytes: 16_384,
+};
+export const PLATFORM_CUSTOM_ENDPOINT_LIMITS = { bindings: 5, baseUrlChars: 2_048, nameChars: 64, templateChars: 256, secretChars: 4_096, headers: 10, query: 10, valueChars: 1_024 };
+export const PLATFORM_METERED_CALL = { includedMs: 5_000, stepMs: 5_000, includedBytes: 1_048_576, stepBytes: 262_144, unitPriceMicros: 300 };
+export const PLATFORM_CUSTOM_ENDPOINT_BOUNDS = { timeoutMs: { standard: PLATFORM_METERED_CALL.includedMs, maximum: 300_000 }, responseMiB: { standard: 1, maximum: 14 } };
+const startedSteps = (amount, included, step) => Math.ceil(Math.max(amount - included, 0) / step);
+export const platformMeteredCallUnits = (elapsedMs, receivedBytes) => startedSteps(elapsedMs, PLATFORM_METERED_CALL.includedMs, PLATFORM_METERED_CALL.stepMs) + startedSteps(receivedBytes, PLATFORM_METERED_CALL.includedBytes, PLATFORM_METERED_CALL.stepBytes);
+export const isExtendedCustomEndpoint = ({ timeoutMs, responseMiB }) => timeoutMs > PLATFORM_CUSTOM_ENDPOINT_BOUNDS.timeoutMs.standard || responseMiB > PLATFORM_CUSTOM_ENDPOINT_BOUNDS.responseMiB.standard;
+export const platformCustomEndpointCostCeiling = (limits) => isExtendedCustomEndpoint(limits)
+    ? platformMeteredCallUnits(limits.timeoutMs, limits.responseMiB * 1_048_576) * PLATFORM_METERED_CALL.unitPriceMicros : 0;
+export const platformCustomToolKindSchema = z.enum(["python", "http"]);
+export const platformCustomEndpointLocationSchema = z.enum(["header", "query"]);
+const HEADER_NAME = /^[A-Za-z0-9_-]{1,64}$/;
+const QUERY_NAME = /^[A-Za-z0-9_.$-]{1,64}$/;
+const FORBIDDEN_BINDING_HEADER = /^(?:keep-alive|trailer|proxy-.*|x-forwarded-.*|x-real-ip|set-cookie|accept-encoding|content-type|accept)$/i;
+const CONTROL = /[\u0000-\u001f\u007f]/;
+export const PLATFORM_CUSTOM_ENDPOINT_SECRET_PLACEHOLDER = "{secret}";
+export function isPlatformCustomEndpointBaseUrl(value) {
+    try {
+        const url = new URL(value);
+        return url.protocol === "https:" && !url.username && !url.password && !url.hash && !url.search && !value.includes("?") && !value.includes("#")
+            && PLATFORM_APP_HOST_PATTERN.test(url.host) && !/(?:^|\/)\.{1,2}(?:\/|$)/.test(url.pathname) && !/[\\\s]/.test(value) && !CONTROL.test(value);
+    }
+    catch {
+        return false;
+    }
+}
+export const platformCustomEndpointBaseUrlSchema = z.string().trim().min(1).max(PLATFORM_CUSTOM_ENDPOINT_LIMITS.baseUrlChars)
+    .refine(isPlatformCustomEndpointBaseUrl, "An https URL on a public host name, without credentials, a query or a fragment")
+    .describe("The API root, e.g. https://api.example.com or https://api.example.com/v1. Requests go to a path under it.");
+const bindingTemplateSchema = z.string().min(1).max(PLATFORM_CUSTOM_ENDPOINT_LIMITS.templateChars)
+    .refine(value => value.includes(PLATFORM_CUSTOM_ENDPOINT_SECRET_PLACEHOLDER) && value.replaceAll(PLATFORM_CUSTOM_ENDPOINT_SECRET_PLACEHOLDER, "").search(/[{}]/) === -1 && !CONTROL.test(value), "The template contains {secret} and no other braces or control characters");
+const bindingNameCheck = (binding) => binding.location === "header"
+    ? HEADER_NAME.test(binding.name) && !PLATFORM_APP_RESERVED_HEADERS.has(binding.name.toLowerCase()) && !FORBIDDEN_BINDING_HEADER.test(binding.name)
+    : QUERY_NAME.test(binding.name);
+const bindingLocation = platformCustomEndpointLocationSchema.describe("header or query: where Relvo puts the credential on every request.");
+const bindingName = z.string().min(1).max(PLATFORM_CUSTOM_ENDPOINT_LIMITS.nameChars).describe("The header or query parameter name, e.g. Authorization or api_key.");
+export const platformCustomEndpointBindingInputSchema = z.object({
+    id: z.string().regex(/^[a-z0-9]{8,32}$/).optional().describe("Only when editing: the id of a saved binding whose secret is kept when no new secret is sent."),
+    location: bindingLocation,
+    name: bindingName,
+    template: bindingTemplateSchema.default(PLATFORM_CUSTOM_ENDPOINT_SECRET_PLACEHOLDER).describe("The value sent, with {secret} where the secret goes, e.g. Bearer {secret}."),
+    secret: z.string().min(1).max(PLATFORM_CUSTOM_ENDPOINT_LIMITS.secretChars).refine(value => !CONTROL.test(value), "The secret has no control characters").optional()
+        .describe("The credential. Required for a new binding without secretRef; sent again only to replace it. Relvo never returns it."),
+    secretRef: platformTeamSecretNameSchema.optional().describe("The name of a saved team secret to use instead of an inline secret. Only the console may set it."),
+}).strict().refine(bindingNameCheck, "A valid header or query parameter name that is not reserved")
+    .refine(binding => binding.id !== undefined || binding.secret !== undefined || binding.secretRef !== undefined, "A new binding needs its secret")
+    .refine(binding => binding.secret === undefined || binding.secretRef === undefined, "A binding takes a secret or a secretRef, not both");
+export const platformCustomEndpointBindingSchema = z.object({ id: z.string(), location: bindingLocation, name: bindingName, template: bindingTemplateSchema,
+    maskedSecret: z.string().nullable(), secretRef: platformTeamSecretNameSchema.nullable().default(null) }).strict();
+export const isPlatformCustomEndpointFixedName = (location, name) => location === "header"
+    ? isPlatformCallerHeaderName(name) && !/^(?:keep-alive|trailer)$/i.test(name)
+    : name.length >= 1 && name.length <= PLATFORM_CUSTOM_ENDPOINT_LIMITS.nameChars && !CONTROL.test(name);
+export const isPlatformCustomEndpointFixedValue = (location, value) => value.length >= 1 && value.length <= PLATFORM_CUSTOM_ENDPOINT_LIMITS.valueChars
+    && !CONTROL.test(value) && (location === "query" || isPlatformHeaderValue(value));
+const fixedValuesSchema = (location) => z.record(z.string(), z.string())
+    .refine(values => Object.keys(values).length <= PLATFORM_CUSTOM_ENDPOINT_LIMITS[location === "header" ? "headers" : "query"], "Too many fixed values")
+    .refine(values => Object.entries(values).every(([name, value]) => isPlatformCustomEndpointFixedName(location, name) && isPlatformCustomEndpointFixedValue(location, value)), `${location === "header" ? "A header a caller may set" : "A name without control characters"}, with a value of 1–${PLATFORM_CUSTOM_ENDPOINT_LIMITS.valueChars} characters that can be sent`)
+    .refine(values => new Set(Object.keys(values).map(name => name.toLowerCase())).size === Object.keys(values).length, "Each name once, in any case");
+export const platformCustomEndpointHeadersSchema = fixedValuesSchema("header")
+    .describe("Fixed, non-secret headers Relvo adds to every request, e.g. {\"X-Api-Version\":\"2024-06-01\"}; anyone who can read the tool sees them, so a credential goes in a binding. A request that sets one of these names is refused.");
+export const platformCustomEndpointQuerySchema = fixedValuesSchema("query")
+    .describe("Fixed, non-secret query parameters Relvo adds to every request, e.g. {\"format\":\"json\"}; anyone who can read the tool sees them, so a credential goes in a binding. A request that sets one of these names is refused.");
+export const platformCustomEndpointSchema = z.object({ baseUrl: platformCustomEndpointBaseUrlSchema,
+    headers: platformCustomEndpointHeadersSchema.optional(), query: platformCustomEndpointQuerySchema.optional(),
+    bindings: z.array(platformCustomEndpointBindingSchema).max(PLATFORM_CUSTOM_ENDPOINT_LIMITS.bindings) }).strict();
+const endpointResponseMiB = z.number().int().min(PLATFORM_CUSTOM_ENDPOINT_BOUNDS.responseMiB.standard).max(PLATFORM_CUSTOM_ENDPOINT_BOUNDS.responseMiB.maximum);
+export const platformStoredCustomEndpointSchema = platformCustomEndpointSchema.extend({ responseMiB: endpointResponseMiB.optional() }).strict();
+export const platformCustomToolSlugSchema = z.string().max(PLATFORM_CUSTOM_TOOL_LIMITS.slugChars).regex(/^[a-z][a-z0-9_]+$/)
+    .describe("Lowercase letters, digits and underscores, starting with a letter; the tool is named custom__<slug>.");
+export const PLATFORM_CUSTOM_TOOL_NAME = /^custom__[a-z][a-z0-9_]{1,39}$/;
+export const platformCustomToolNameSchema = z.string().regex(PLATFORM_CUSTOM_TOOL_NAME);
+export const isPlatformCustomToolName = (name) => PLATFORM_CUSTOM_TOOL_NAME.test(name);
+export const platformCustomToolInputSchemaSchema = platformJsonObjectSchema
+    .refine(schema => schema.type === "object" && schema.properties !== null && typeof schema.properties === "object" && !Array.isArray(schema.properties), "The input schema is an object schema with properties")
+    .refine(schema => new TextEncoder().encode(JSON.stringify(schema)).byteLength <= PLATFORM_CUSTOM_TOOL_LIMITS.schemaBytes, "The input schema is too large");
+export const platformCustomToolDefinitionSchema = z.object({
+    kind: z.literal("python").default("python"),
+    title: z.string().trim().min(1).max(PLATFORM_CUSTOM_TOOL_LIMITS.titleChars),
+    description: z.string().trim().min(1).max(PLATFORM_CUSTOM_TOOL_LIMITS.descriptionChars).describe("What the tool does and returns; agents choose tools by it."),
+    inputSchema: platformCustomToolInputSchemaSchema.describe("JSON Schema of the input object, e.g. {\"type\":\"object\",\"properties\":{\"days\":{\"type\":\"integer\"}},\"required\":[\"days\"]}."),
+    code: z.string().min(1).max(PLATFORM_CUSTOM_TOOL_LIMITS.codeChars)
+        .describe("Python. The validated input is the dict `input`; print the result (JSON is easiest to read back). Files of sourceExecutionIds are listed in /home/user/tool-results/manifest.json. No credentials are present."),
+    timeoutMs: z.number().int().min(1000).max(PLATFORM_SANDBOX_LIMITS.timeoutMs).default(30_000),
+    enabled: z.boolean().default(true),
+}).strict();
+const uniqueBindings = (bindings) => new Set(bindings.map(binding => `${binding.location}:${binding.name.toLowerCase()}`)).size === bindings.length;
+export const platformCustomEndpointDefinitionSchema = z.object({
+    kind: z.literal("http"),
+    title: z.string().trim().min(1).max(PLATFORM_CUSTOM_TOOL_LIMITS.titleChars),
+    description: z.string().trim().min(1).max(PLATFORM_CUSTOM_TOOL_LIMITS.descriptionChars).describe("What the API is and when to use it; agents choose tools by it."),
+    baseUrl: platformCustomEndpointBaseUrlSchema,
+    headers: platformCustomEndpointHeadersSchema.optional(),
+    query: platformCustomEndpointQuerySchema.optional(),
+    bindings: z.array(platformCustomEndpointBindingInputSchema).max(PLATFORM_CUSTOM_ENDPOINT_LIMITS.bindings).refine(uniqueBindings, "Each header or query parameter is bound once").default([])
+        .describe("Credentials Relvo adds to every request, in the header or query parameter named. Agents never see them. Empty for an API that needs none."),
+    timeoutMs: z.number().int().min(PLATFORM_CUSTOM_ENDPOINT_BOUNDS.timeoutMs.standard).max(PLATFORM_CUSTOM_ENDPOINT_BOUNDS.timeoutMs.maximum).default(PLATFORM_CUSTOM_ENDPOINT_BOUNDS.timeoutMs.standard)
+        .describe("How long one call may take, in milliseconds, 5000 to 300000. Above 5000 every call is metered: USD 0.0003 for each started 5 seconds after the first 5 and each started 256 KiB after the first 1 MiB, with both limits reserved before it runs."),
+    responseMiB: endpointResponseMiB.default(PLATFORM_CUSTOM_ENDPOINT_BOUNDS.responseMiB.standard)
+        .describe("The largest response a call keeps, in MiB, 1 to 14. Above 1 every call is metered as for timeoutMs."),
+    enabled: z.boolean().default(true),
+}).strict();
+const fixedApartFromBindings = (endpoint) => endpoint.bindings.every(binding => !Object.keys((binding.location === "header" ? endpoint.headers : endpoint.query) ?? {}).some(name => name.toLowerCase() === binding.name.toLowerCase()));
+const apart = { message: "A header or query parameter is either fixed or bound, not both", path: ["bindings"] };
+const slugged = { slug: platformCustomToolSlugSchema };
+const versioned = { expectedVersion: z.number().int().min(1) };
+export const platformCustomToolCreateSchema = z.union([platformCustomToolDefinitionSchema.extend(slugged).strict(),
+    platformCustomEndpointDefinitionSchema.extend(slugged).strict().refine(fixedApartFromBindings, apart)]);
+export const platformCustomToolUpdateSchema = z.union([platformCustomToolDefinitionSchema.extend(versioned).strict(),
+    platformCustomEndpointDefinitionSchema.extend(versioned).strict().refine(fixedApartFromBindings, apart)]);
+export const platformCustomToolRestoreSchema = z.object({ version: z.number().int().min(1), expectedVersion: z.number().int().min(1) }).strict();
+export const platformCustomToolSchema = z.object({
+    kind: platformCustomToolKindSchema.default("python"), endpoint: platformCustomEndpointSchema.nullable().default(null),
+    name: platformCustomToolNameSchema, slug: platformCustomToolSlugSchema, title: z.string(), description: z.string(), inputSchema: platformJsonObjectSchema,
+    code: z.string(), timeoutMs: z.number().int(), responseMiB: endpointResponseMiB.default(PLATFORM_CUSTOM_ENDPOINT_BOUNDS.responseMiB.standard),
+    enabled: z.boolean(), version: z.number().int().min(1), createdAt: z.string(), updatedAt: z.string(),
+});
+export const platformCustomToolSummarySchema = platformCustomToolSchema.omit({ code: true, inputSchema: true });
+export const platformCustomToolVersionSchema = z.object({ version: z.number().int().min(1), title: z.string(), createdAt: z.string() });
+export const platformVersionAuthorSchema = z.object({ email: z.string().nullable(), apiKey: z.string().nullable() }).strict();
+export const platformCustomToolHistorySchema = platformCustomToolVersionSchema.extend({ author: platformVersionAuthorSchema });
+export const platformCustomToolVersionDetailSchema = platformCustomToolSchema.pick({ kind: true, endpoint: true, title: true, description: true, inputSchema: true, code: true, timeoutMs: true, responseMiB: true, enabled: true })
+    .extend({ version: z.number().int().min(1), createdAt: z.string(), author: platformVersionAuthorSchema });
+const toolInput = projectScopeSchema.extend({ name: platformCustomToolNameSchema });
+const toolResult = z.object({ tool: platformCustomToolSchema }).strict();
+export const platformCustomToolContracts = {
+    listDeveloperCustomTools: { input: projectScopeSchema.strict(), output: z.object({ tools: z.array(platformCustomToolSummarySchema) }).strict() },
+    getDeveloperCustomTool: { input: toolInput.strict(), output: toolResult },
+    createDeveloperCustomTool: { input: projectScopeSchema.extend({ tool: platformCustomToolCreateSchema }).strict(), output: toolResult },
+    updateDeveloperCustomTool: { input: toolInput.extend({ tool: platformCustomToolUpdateSchema }).strict(), output: toolResult },
+    restoreDeveloperCustomTool: { input: toolInput.merge(platformCustomToolRestoreSchema).strict(), output: toolResult },
+    deleteDeveloperCustomTool: { input: toolInput.strict(), output: z.object({ success: z.literal(true) }).strict() },
+    listDeveloperCustomToolVersions: { input: toolInput.strict(), output: z.object({ versions: z.array(platformCustomToolHistorySchema) }).strict() },
+    getDeveloperCustomToolVersion: { input: toolInput.extend({ version: z.number().int().min(1) }).strict(), output: z.object({ version: platformCustomToolVersionDetailSchema }).strict() },
+};

package/dist/schema/platformEndUserApi.js

@@ -0,0 +1,62 @@
+import { z } from "zod";
+import { PLATFORM_APP_LIMITS, platformAppOAuthClientSchema, platformAppScopesSchema } from "./platformAppAuth.js";
+import { platformAppIdSchema, platformConnectionCatalogQuerySchema, platformAnyConnectionProviderSchema, PLATFORM_CONNECTION_PAGE_MAX } from "./platformConnectionCatalog.js";
+import { platformConnectionOperationsSchema } from "./platformConnectionPolicy.js";
+import { platformToolNameSchema } from "./platformPublicExecution.js";
+import { PLATFORM_API_KEY_PATTERN } from "./platformApiKey.js";
+import { USAGE_BREAKDOWN_MAX_DAYS } from "./platformBillingConstants.js";
+export const PLATFORM_CONNECT_LINK_LIMITS = { lifetimeMinutes: 60, activePerProject: 100, fields: PLATFORM_APP_LIMITS.fields, callbackChars: 2048 };
+export const PLATFORM_END_USER_LIMITS = { idChars: 128, sessionMinutes: 60, tools: 500, usageOperations: 100 };
+export const PLATFORM_END_USER_ROUTES = {
+    links: "/v1/connect-links", sessions: "/v1/sessions", session: "/v1/sessions/:id{[a-f0-9-]{36}}",
+    revokeSession: "/v1/sessions/:id{[a-f0-9-]{36}}/revoke", users: "/v1/users", setUser: "/v1/users/update",
+    restoreSession: "/v1/sessions/restore", userUsage: "/v1/users/:userId{[A-Za-z0-9._:@%-]+}/usage",
+    linkStatus: "/v1/connect-links/status", revokeLink: "/v1/connect-links/revoke",
+    connections: "/v1/users/:userId{[A-Za-z0-9._:@%-]+}/connections", disconnect: "/v1/users/connections/disconnect",
+};
+export const platformEndUserIdSchema = z.string().trim().min(1).max(PLATFORM_END_USER_LIMITS.idChars).regex(/^[A-Za-z0-9._:@-]+$/);
+export const platformConnectCallbackUrlSchema = z.url().max(PLATFORM_CONNECT_LINK_LIMITS.callbackChars).refine(value => {
+    const url = new URL(value);
+    return !url.username && !url.password && (url.protocol === "https:" || url.protocol === "http:" && ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname));
+});
+export const platformConnectMethodSchema = z.enum(["oauth2", "oauth1", "mcp_oauth", "key", "client_credentials", "service_account"]);
+export const platformConnectLinkDefinitionSchema = z.object({
+    appId: platformAppIdSchema, method: platformConnectMethodSchema,
+    oauthClient: platformAppOAuthClientSchema.optional(), scopes: platformAppScopesSchema.optional(),
+    operations: platformConnectionOperationsSchema.optional(),
+}).strict();
+export const platformConnectLinkTokenSchema = z.string().regex(/^[A-Za-z0-9_-]{43}$/);
+const numericQuery = (value) => typeof value === "string" && value.trim() !== "" ? Number(value) : value;
+const customerConnection = z.object({ id: z.string(), provider: platformAnyConnectionProviderSchema, label: z.string(),
+    status: z.enum(["connected", "reauth_required"]), scopes: z.array(z.string()), createdAt: z.string() });
+export const platformEndUserContracts = {
+    createLink: { input: z.object({ userId: platformEndUserIdSchema, connection: platformConnectLinkDefinitionSchema, callbackUrl: platformConnectCallbackUrlSchema.optional(),
+            expiresInMinutes: z.number().int().min(1).max(PLATFORM_CONNECT_LINK_LIMITS.lifetimeMinutes).default(30) }).strict(), output: z.object({ url: z.url(), expiresAt: z.iso.datetime() }) },
+    linkStatus: { input: z.object({ token: platformConnectLinkTokenSchema }).strict(), output: z.object({ userId: platformEndUserIdSchema, appId: platformAppIdSchema, expiresAt: z.iso.datetime(),
+            status: z.enum(["pending", "authorizing", "selecting", "completed", "failed", "expired", "revoked", "unavailable"]), connectionId: z.string().nullable() }) },
+    revokeLink: { input: z.object({ token: platformConnectLinkTokenSchema }).strict(), output: z.object({ success: z.literal(true) }) },
+    connections: { input: platformConnectionCatalogQuerySchema.omit({ provider: true }).extend({ userId: platformEndUserIdSchema,
+            offset: z.preprocess(numericQuery, platformConnectionCatalogQuerySchema.shape.offset), limit: z.preprocess(numericQuery, platformConnectionCatalogQuerySchema.shape.limit) }).strict(),
+        output: z.object({ connections: z.array(customerConnection).max(PLATFORM_CONNECTION_PAGE_MAX), total: z.number().int().nonnegative(), nextOffset: z.number().int().nonnegative().nullable() }) },
+    disconnect: { input: z.object({ userId: platformEndUserIdSchema, connectionId: z.string().min(1).max(128) }).strict(), output: z.object({ success: z.literal(true) }) },
+    createSession: { input: z.object({ userId: platformEndUserIdSchema, tools: z.array(platformToolNameSchema).max(PLATFORM_END_USER_LIMITS.tools).optional(),
+            expiresInMinutes: z.number().int().min(1).max(PLATFORM_END_USER_LIMITS.sessionMinutes).default(30) }).strict(), output: z.object({
+            id: z.uuid(), userId: platformEndUserIdSchema, expiresAt: z.iso.datetime(), mcp: z.object({ url: z.url(), headers: z.object({ Authorization: z.string() }) }),
+        }) },
+    session: { input: z.object({ id: z.uuid() }).strict(), output: z.object({ id: z.uuid(), userId: platformEndUserIdSchema, expiresAt: z.iso.datetime(), active: z.boolean() }) },
+    revokeSession: { input: z.object({ id: z.uuid() }).strict(), output: z.object({ success: z.literal(true) }) },
+    users: { input: z.object({ limit: z.coerce.number().int().min(1).max(100).default(30), after: platformEndUserIdSchema.optional() }).strict(),
+        output: z.object({ users: z.array(z.object({ id: platformEndUserIdSchema, active: z.boolean(), connections: z.number().int().nonnegative() })), nextCursor: z.string().nullable() }) },
+    setUser: { input: z.object({ userId: platformEndUserIdSchema, active: z.boolean() }).strict(), output: z.object({ success: z.literal(true) }) },
+    restoreSession: { input: z.object({ id: z.uuid(), token: z.string().regex(PLATFORM_API_KEY_PATTERN) }).strict(),
+        output: z.object({ id: z.uuid(), userId: platformEndUserIdSchema, expiresAt: z.iso.datetime(), mcp: z.object({ url: z.url(), headers: z.object({ Authorization: z.string() }) }) }) },
+};
+const usageTotals = z.object({ requests: z.number().int().nonnegative(), succeeded: z.number().int().nonnegative(), failed: z.number().int().nonnegative(),
+    pending: z.number().int().nonnegative(), chargedMicros: z.number().int().nonnegative(), reservedMicros: z.number().int().nonnegative() });
+export const platformEndUserUsageContract = {
+    input: z.object({ userId: platformEndUserIdSchema, from: z.iso.date(), to: z.iso.date() }).strict().refine(value => value.from >= "0001-01-01" && value.from <= value.to
+        && (Date.parse(value.to) - Date.parse(value.from)) / 86_400_000 < USAGE_BREAKDOWN_MAX_DAYS),
+    output: z.object({ userId: platformEndUserIdSchema, from: z.iso.date(), to: z.iso.date(), currency: z.literal("usd"), summary: usageTotals,
+        daily: z.array(usageTotals.extend({ day: z.iso.date() })).max(USAGE_BREAKDOWN_MAX_DAYS),
+        byOperation: z.object({ rows: z.array(usageTotals.extend({ operation: z.string() })).max(PLATFORM_END_USER_LIMITS.usageOperations), other: usageTotals.nullable() }) }),
+};

package/dist/schema/platformFunding.js

@@ -0,0 +1,10 @@
+import { z } from "zod";
+import { PLATFORM_CHECKOUT_MIN_CENTS } from "./platformBillingConstants.js";
+const micros = z.string().regex(/^\d{1,20}$/);
+export const platformFundingShortfallSchema = z.object({
+    reason: z.enum(["balance", "organization_monthly_limit", "project_monthly_limit", "member_monthly_limit", "organization_daily_limit", "api_key_daily_limit"]),
+    requiredMicros: micros,
+    availableMicros: micros,
+});
+export const platformFundingRecoverySchema = z.object({ billingUrl: z.url({ protocol: /^https?$/ }), shortfall: platformFundingShortfallSchema.optional() });
+export const PLATFORM_WALLET_TOP_UP_MIN_CENTS = PLATFORM_CHECKOUT_MIN_CENTS;

package/dist/schema/platformHttpConstraints.js

@@ -0,0 +1,12 @@
+import { z } from "zod";
+import { ACCOUNT_REQUEST_HTTP_METHODS } from "./accountRequestMethods.js";
+export const PLATFORM_APP_HOST_PATTERN = /^(?=[^:]{4,253}(?::|$))(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z][a-z0-9-]{0,61}[a-z0-9](?::[1-9][0-9]{0,4})?$/;
+export const PLATFORM_APP_RESERVED_HEADERS = new Set(["host", "cookie", "content-length", "transfer-encoding", "connection", "proxy-authorization", "forwarded", "te", "upgrade", "expect"]);
+export const PLATFORM_CREDENTIAL_HEADER = /^(?:authorization|x-api-key|api-key|apikey|x-auth-token|x-access-token|cookie|set-cookie|proxy-.*|x-forwarded-.*|x-real-ip)$/i;
+export const isPlatformCallerHeaderName = (name) => /^[A-Za-z0-9_-]{1,64}$/.test(name) && !PLATFORM_APP_RESERVED_HEADERS.has(name.toLowerCase())
+    && !PLATFORM_CREDENTIAL_HEADER.test(name) && !/^(?:x-http-method-override|x-http-method|x-method-override)$/i.test(name);
+export const isPlatformHeaderValue = (value) => !/[\r\n\u0000]|[^\x00-\xff]/.test(value);
+export const PLATFORM_APP_MAX_BASE_URLS = 32;
+export const platformAppApiPathSchema = z.object({ baseUrl: z.number().int().min(0).max(PLATFORM_APP_MAX_BASE_URLS), method: z.enum(ACCOUNT_REQUEST_HTTP_METHODS),
+    path: z.string().startsWith("/").max(2048).refine(path => !/[?#\\\s\u0000-\u001f]/.test(path) && !path.includes("//")
+        && path.split("/").every(segment => segment !== "." && segment !== ".." && (!/[{}]/.test(segment) || /^\{[A-Za-z_][A-Za-z0-9_]*\}$/.test(segment)))) }).strict();

package/dist/schema/platformLocalSetup.js

@@ -0,0 +1,25 @@
+import { z } from "zod";
+import { developerKeyScopeSchema } from "./platformPublicExecution.js";
+import { PLATFORM_API_KEY_PATTERN } from "./platformApiKey.js";
+export const PLATFORM_LOCAL_SETUP_TTL_SECONDS = 600;
+export const PLATFORM_LOCAL_SETUP_INTERVAL_SECONDS = 5;
+export const platformLocalSetupClientSchema = z.enum(["claude", "codex", "agents", "terminal"]);
+export const platformLocalSetupAuthorizationSchema = z.string().min(1).max(4096);
+export const platformLocalSetupStartInputSchema = z.object({ client: platformLocalSetupClientSchema }).strict();
+export const platformLocalSetupProofSchema = z.object({ authorizationRequest: platformLocalSetupAuthorizationSchema,
+    deviceCode: z.string().regex(/^[A-Za-z0-9_-]{43}$/) }).strict();
+export const platformLocalSetupStartSchema = z.object({ authorizationRequest: platformLocalSetupAuthorizationSchema,
+    deviceCode: platformLocalSetupProofSchema.shape.deviceCode, userCode: z.string().regex(/^[A-Z2-9]{4}-[A-Z2-9]{4}$/),
+    verificationUri: z.url(), expiresAt: z.iso.datetime(), intervalSeconds: z.literal(PLATFORM_LOCAL_SETUP_INTERVAL_SECONDS) }).strict();
+const grantMetadata = { apiKeyId: z.string(), developerOrganizationId: z.string(), developerProjectId: z.string(),
+    scopes: z.array(developerKeyScopeSchema).min(1).max(5), expiresAt: z.iso.datetime(), approvedExpiresAt: z.iso.datetime() };
+export const platformLocalSetupAcknowledgedSchema = z.object({ status: z.literal("acknowledged"), ...grantMetadata }).strict();
+export const platformLocalSetupPollSchema = z.discriminatedUnion("status", [
+    z.object({ status: z.literal("pending"), expiresAt: z.iso.datetime(), intervalSeconds: z.literal(PLATFORM_LOCAL_SETUP_INTERVAL_SECONDS) }).strict(),
+    z.object({ status: z.literal("approved"), apiKey: z.string().regex(PLATFORM_API_KEY_PATTERN), ...grantMetadata }).strict(),
+    platformLocalSetupAcknowledgedSchema,
+]);
+export const platformLocalSetupMetadataSchema = z.object({ client: platformLocalSetupClientSchema,
+    expiresAt: z.iso.datetime(), status: z.enum(["pending", "approved", "acknowledged"]),
+    apiKeyId: z.string().optional(), developerOrganizationId: z.string().optional(), developerProjectId: z.string().optional(),
+    scopes: z.array(developerKeyScopeSchema).optional(), approvedExpiresAt: z.iso.datetime().optional(), requestedFrom: z.string().optional() }).strict();

package/dist/schema/platformMcpTools.js

@@ -0,0 +1,7 @@
+export const PLATFORM_MCP_DIRECT_TOOLS_MAX = 20;
+export function platformMcpDirectToolNames(list) {
+    const names = [...new Set((list ?? "").split(",").map(name => name.trim()).filter(Boolean))];
+    if (names.length > PLATFORM_MCP_DIRECT_TOOLS_MAX || names.some(name => !/^[a-z][a-z0-9_]{1,63}$/u.test(name)))
+        throw new Error(`Name at most ${PLATFORM_MCP_DIRECT_TOOLS_MAX} catalog tools, separated by commas.`);
+    return names;
+}

package/dist/schema/platformMetaTools.js

@@ -0,0 +1,63 @@
+import { z } from "zod";
+import { platformCatalogSchema, platformCreateExecutionSchema, platformExecutionIdSchema, platformExecutionStatusSchema, platformMicrosSchema, platformQuoteSchema, platformToolNameSchema, platformToolSessionIdSchema, platformOptionalToolSessionIdSchema, PLATFORM_SANDBOX_LIMITS, platformExecutionSchema, platformExecutionContextSchema, platformRequestIntentSchema, validatePlatformArgumentIdentifiers, PLATFORM_TOOL_REQUEST_MAX_BYTES } from "./platformPublicExecution.js";
+import { platformAnyConnectionProviderSchema, platformConnectionCatalogSchema } from "./platformConnectionCatalog.js";
+import { toolDiscoveryInputSchema, toolDiscoveryResultSchema } from "./toolDiscovery.js";
+import { platformFundingRecoverySchema } from "./platformFunding.js";
+export { PLATFORM_MCP_DIRECT_TOOLS_MAX, platformMcpDirectToolNames } from "./platformMcpTools.js";
+export const PLATFORM_META_LIMITS = { queries: 4, schemas: 12, batch: 50, concurrency: 4, contextBytes: 24_000,
+    requestBytes: PLATFORM_TOOL_REQUEST_MAX_BYTES, requestTimeoutMs: 90_000, sessionLifetimeMs: 86_400_000, activeSessions: 100,
+    codeChars: PLATFORM_SANDBOX_LIMITS.code, commandChars: 16_000, sourceExecutions: PLATFORM_SANDBOX_LIMITS.sourceExecutions, timeoutMs: PLATFORM_SANDBOX_LIMITS.timeoutMs };
+export const isSessionSandboxTool = (name) => name === "remote_workbench" || name === "remote_bash";
+export const platformToolSessionSchema = z.object({ id: platformToolSessionIdSchema, expiresAt: z.iso.datetime(),
+    sandbox: z.enum(["new", "ready", "busy", "needs_review", "state_lost"]), activeExecutionId: platformExecutionIdSchema.nullable() });
+const sessionInput = { sessionId: platformToolSessionIdSchema };
+export const platformMetaSearchSchema = z.object({ sessionId: platformOptionalToolSessionIdSchema.describe("Continue a returned session. Omit or use an empty string to open a new session."),
+    intent: platformRequestIntentSchema,
+    queries: z.array(toolDiscoveryInputSchema).min(1).max(PLATFORM_META_LIMITS.queries)
+        .describe("Independent capability queries, one action per query. Use exact app names when known; omit private account data.") }).strict();
+export const platformMetaSearchResultSchema = z.object({ session: platformToolSessionSchema,
+    results: z.array(z.object({ query: z.string().optional(), ...toolDiscoveryResultSchema.shape })),
+    nextSteps: z.array(z.enum(["inspect_schemas", "check_connections", "quote", "execute_independent", "process_results"])) });
+export const platformMetaSchemasSchema = z.object({ ...sessionInput,
+    tools: z.array(platformToolNameSchema).min(1).max(PLATFORM_META_LIMITS.schemas).refine(names => new Set(names).size === names.length, "Tool names must be unique") }).strict();
+export const platformMetaSchemasResultSchema = z.object({ session: platformToolSessionSchema,
+    tools: platformCatalogSchema.shape.tools, remaining: z.array(platformToolNameSchema) });
+export const platformMetaConnectionsSchema = z.object({ ...sessionInput,
+    providers: z.array(platformAnyConnectionProviderSchema).max(32).default([])
+        .describe("Providers to inspect: OAuth providers or connected apps as app:<id> (e.g. app:airtable). Empty means every connection. Data-provider API keys are managed by Relvo.") }).strict();
+export const platformMetaConnectionsResultSchema = z.object({ session: platformToolSessionSchema,
+    developerOrganizationId: z.string(), developerProjectId: z.string(),
+    manageUrl: z.url().nullable(), connections: platformConnectionCatalogSchema.shape.connections,
+    total: z.number().int().nonnegative(), providers: z.array(z.object({ provider: platformAnyConnectionProviderSchema,
+        status: z.enum(["connected", "reauth_required", "not_connected"]) })),
+    instruction: z.string() });
+const item = z.object(platformCreateExecutionSchema.shape).omit({ sessionId: true }).extend({ idempotencyKey: z.string().regex(/^[A-Za-z0-9._:-]{8,128}$/) }).strict()
+    .superRefine((value, context) => validatePlatformArgumentIdentifiers(value.tool, value.arguments, context));
+export const platformMetaExecuteSchema = z.object({ ...sessionInput,
+    maximumChargeMicros: platformMicrosSchema.describe("Accepted total reservation ceiling across this batch, in addition to each accepted quote."),
+    tools: z.array(item).min(1).max(PLATFORM_META_LIMITS.batch)
+        .describe("Logically independent, quoted calls only. Dependent calls must wait for their inputs in a later batch.") }).strict().superRefine((value, ctx) => {
+    if (new Set(value.tools.map(tool => tool.idempotencyKey)).size !== value.tools.length)
+        ctx.addIssue({ code: "custom", path: ["tools"], message: "Each call needs its own retained idempotency key" });
+    if (value.tools.reduce((total, tool) => total + tool.maximumChargeMicros, 0) > value.maximumChargeMicros)
+        ctx.addIssue({ code: "custom", path: ["maximumChargeMicros"], message: "Batch exceeds the accepted reservation ceiling" });
+});
+export const platformMetaExecuteResultSchema = z.object({ session: platformToolSessionSchema,
+    allAccepted: z.boolean(),
+    results: z.array(z.object({ index: z.number().int().nonnegative(), tool: platformToolNameSchema, idempotencyKey: z.string(),
+        admission: z.enum(["accepted", "rejected", "unknown"]), executionId: platformExecutionIdSchema.optional(),
+        status: platformExecutionStatusSchema.optional(), reservedMicros: platformMicrosSchema.optional(),
+        errorCode: z.string().optional(), fundingRecovery: platformFundingRecoverySchema.optional() })),
+    instruction: z.string() });
+const remote = { ...sessionInput, timeoutMs: z.number().int().min(1000).max(PLATFORM_META_LIMITS.timeoutMs).default(30_000),
+    intent: platformRequestIntentSchema,
+    sourceExecutionIds: z.array(platformExecutionIdSchema).max(PLATFORM_META_LIMITS.sourceExecutions).default([])
+        .refine(ids => new Set(ids).size === ids.length, "Source execution IDs must be unique"),
+    quote: platformQuoteSchema,
+    idempotencyKey: item.shape.idempotencyKey };
+export const platformMetaWorkbenchSchema = z.object({ ...remote,
+    code: z.string().min(1).max(PLATFORM_META_LIMITS.codeChars).describe("Python cell in this session's remote sandbox. Variables and files persist. Process prior outputs via sourceExecutionIds; no provider credentials or direct tool proxy are present.") }).strict();
+export const platformMetaBashSchema = z.object({ ...remote,
+    command: z.string().min(1).max(PLATFORM_META_LIMITS.commandChars).describe("Bash command in this session's remote sandbox, never on the user's machine. Shares files with Python. No provider credentials are present.") }).strict();
+export const platformMetaRemoteResultSchema = z.object({ session: platformToolSessionSchema,
+    execution: z.union([platformExecutionContextSchema, platformExecutionSchema]) });

package/dist/schema/platformMonitorSchedule.js

@@ -0,0 +1,123 @@
+import { z } from "zod";
+import { isCronTooFrequent, isValidCron, parseCron } from "./cronValidator.js";
+import { ScheduleTimeZone } from "./scheduleTimeZone.js";
+export const PLATFORM_MONITOR_INTERVALS = { "15m": 900, "1h": 3600, "1d": 86_400 };
+export const platformMonitorIntervalSchema = z.enum(["15m", "1h", "1d"]);
+export const PLATFORM_MONITOR_DEFAULT_INTERVAL = "1h";
+export const PLATFORM_MONITOR_DEFAULT_TIME_ZONE = "UTC";
+export const PLATFORM_MONITOR_MIN_CRON_MINUTES = 15;
+export const PLATFORM_MONITOR_CRON_CHARS = 100;
+const cronText = z.string().trim().max(PLATFORM_MONITOR_CRON_CHARS)
+    .refine(isValidCron, "platform_monitor_cron_invalid")
+    .refine(cron => !isCronTooFrequent(cron, PLATFORM_MONITOR_MIN_CRON_MINUTES), "platform_monitor_cron_too_frequent");
+export const platformMonitorCronSchema = z.union([z.literal(""), cronText]);
+export const platformMonitorTimeZoneSchema = z.union([z.literal(""), ScheduleTimeZone]);
+export const normalizeMonitorCron = (cron) => cron.trim().split(/\s+/).map(field => field.toUpperCase()).join(" ");
+export class PlatformMonitorScheduleError extends Error {
+}
+export function resolvePlatformMonitorSchedule(input, after = Date.now()) {
+    if (!input.cron) {
+        if (input.timeZone)
+            throw new PlatformMonitorScheduleError("platform_monitor_time_zone_needs_cron");
+        return { interval: input.interval ?? PLATFORM_MONITOR_DEFAULT_INTERVAL };
+    }
+    if (input.interval)
+        throw new PlatformMonitorScheduleError("platform_monitor_schedule_conflict");
+    const zone = ScheduleTimeZone.safeParse(input.timeZone || PLATFORM_MONITOR_DEFAULT_TIME_ZONE);
+    if (!zone.success)
+        throw new PlatformMonitorScheduleError("platform_monitor_time_zone_invalid");
+    const cron = normalizeMonitorCron(input.cron), timeZone = zone.data;
+    if (nextCronFire(cron, timeZone, after) === null)
+        throw new PlatformMonitorScheduleError("platform_monitor_cron_never_runs");
+    return { cron, timeZone };
+}
+const MINUTE = 60_000, HOUR = 3_600_000, DAY = 86_400_000;
+const SEARCH_DAYS = 366 * 8;
+const formatters = new Map();
+function offsetAt(timeZone, at) {
+    let format = formatters.get(timeZone);
+    if (!format) {
+        format = new Intl.DateTimeFormat("en-US", { timeZone, hourCycle: "h23", year: "numeric", month: "numeric", day: "numeric", hour: "numeric", minute: "numeric", second: "numeric" });
+        formatters.set(timeZone, format);
+    }
+    const part = {};
+    for (const { type, value } of format.formatToParts(at))
+        if (type !== "literal")
+            part[type] = Number(value);
+    return Date.UTC(part.year, part.month - 1, part.day, part.hour, part.minute, part.second) - Math.floor(at / 1000) * 1000;
+}
+function instantOf(timeZone, wall) {
+    const before = offsetAt(timeZone, wall - DAY), after = offsetAt(timeZone, wall + DAY);
+    const candidates = [...new Set([wall - before, wall - after])].sort((a, b) => a - b);
+    const valid = candidates.filter(at => offsetAt(timeZone, at) === wall - at);
+    if (valid.length)
+        return valid[0];
+    let low = candidates[0], high = candidates[candidates.length - 1];
+    if (low === high)
+        return low;
+    const lowOffset = offsetAt(timeZone, low);
+    while (high - low > MINUTE) {
+        const mid = low + Math.floor((high - low) / (2 * MINUTE)) * MINUTE;
+        if (offsetAt(timeZone, mid) === lowOffset)
+            low = mid;
+        else
+            high = mid;
+    }
+    return high;
+}
+const dayMatches = (parsed, year, month, day) => {
+    if (!parsed.months.has(month))
+        return false;
+    const dom = parsed.daysOfMonth.has(day), dow = parsed.daysOfWeek.has(new Date(Date.UTC(year, month - 1, day)).getUTCDay());
+    return parsed.dayRestrictionOr ? dom || dow : dom && dow;
+};
+const ascending = (values) => [...values].sort((a, b) => a - b);
+export function nextCronFire(cron, timeZone, after) {
+    const parsed = parseCron(cron);
+    if (!parsed)
+        return null;
+    const hours = ascending(parsed.hours), minutes = ascending(parsed.minutes);
+    const wallAfter = after + offsetAt(timeZone, after);
+    const first = new Date(wallAfter);
+    const start = Date.UTC(first.getUTCFullYear(), first.getUTCMonth(), first.getUTCDate()) - DAY;
+    for (let index = 0; index < SEARCH_DAYS; index++) {
+        const dayStart = start + index * DAY, date = new Date(dayStart);
+        if (!dayMatches(parsed, date.getUTCFullYear(), date.getUTCMonth() + 1, date.getUTCDate()))
+            continue;
+        for (const hour of hours)
+            for (const minute of minutes) {
+                const wall = dayStart + hour * HOUR + minute * MINUTE;
+                if (wall < wallAfter - 6 * HOUR)
+                    continue;
+                const at = instantOf(timeZone, wall);
+                if (at > after)
+                    return at;
+            }
+    }
+    return null;
+}
+export function upcomingCronFires(cron, timeZone, after, count) {
+    const fires = [];
+    for (let at = after; fires.length < count;) {
+        const next = nextCronFire(cron, timeZone, at);
+        if (next === null)
+            break;
+        fires.push(next);
+        at = next;
+    }
+    return fires;
+}
+export function monitorRunsPerMonth(schedule) {
+    if (!("cron" in schedule))
+        return Math.round((365 / 12) * 86_400 / PLATFORM_MONITOR_INTERVALS[schedule.interval]);
+    const parsed = parseCron(schedule.cron);
+    if (!parsed)
+        return 0;
+    let days = 0;
+    for (let index = 0; index < 365; index++) {
+        const date = new Date(Date.UTC(2026, 0, 1 + index));
+        if (dayMatches(parsed, date.getUTCFullYear(), date.getUTCMonth() + 1, date.getUTCDate()))
+            days++;
+    }
+    return Math.round(days * parsed.hours.size * parsed.minutes.size / 12);
+}