@opengeni/contracts 5.5.0 → 5.5.2-canary.40656248492001

package/dist/app-actions.d.ts

@@ -0,0 +1,91 @@
+import { ACTION_CATALOG } from "./app-action-catalog.gen.js";
+import type { ActionCatalogEntry } from "./app-action-catalog-types.js";
+import { type PresentedAppActionPage } from "./session-history.js";
+export type { ActionCatalogEntry };
+export { ACTION_CATALOG };
+/** The tool that runs an app action in a session; the only one that can change anything. */
+export declare const APP_ACTION_CALL_TOOL_NAME: "admin_action_call";
+/**
+ * Requests that only read but are sent as POST (a search query or a file path
+ * in the body). Read only connections may run them; each route still checks
+ * its own read permission.
+ */
+export declare const READ_ONLY_POST_ACTIONS: ReadonlySet<string>;
+/** An action by its id, or by "METHOD /path". */
+export declare function findAppAction(id: string): ActionCatalogEntry | undefined;
+/**
+ * Whether running the action can change anything. Only GET, HEAD and the
+ * read-only POSTs can't.
+ */
+export declare function appActionChangesState(entry: ActionCatalogEntry): boolean;
+/**
+ * Whether an admin_action_call with these arguments needs the person's
+ * confirmation when the session lacks full access: true for every change, and
+ * for anything that can't be recognised as a read (unknown action, bad input).
+ */
+export declare function appActionCallChangesState(args: unknown): boolean;
+/**
+ * Actions that only open a payment page (Stripe Checkout or the billing
+ * portal); the chat shows the page as a button. See
+ * {@link appActionNeedsConfirmation} for which of them still ask first.
+ */
+export declare const PAYMENT_PAGE_ACTIONS: ReadonlySet<string>;
+/** The payment page the action opens (see {@link PAYMENT_PAGE_ACTIONS}), if it opens one. */
+export declare function appActionPaymentPage(entry: ActionCatalogEntry): PresentedAppActionPage | undefined;
+/**
+ * Whether running the action needs the person's confirmation in the chat
+ * first, and so can't run where the chat can only read: every change, except
+ * opening a checkout page. A checkout charges nothing until the person pays
+ * on it, so the page is its own confirmation. A billing portal link is
+ * different: whoever holds it can change the payment method or cancel the
+ * plan, so it keeps the confirmation.
+ */
+export declare function appActionNeedsConfirmation(entry: ActionCatalogEntry): boolean;
+/**
+ * The same, for an admin_action_call's arguments: also true for anything that
+ * can't be recognised (unknown action, bad input).
+ */
+export declare function appActionCallNeedsConfirmation(args: unknown): boolean;
+/**
+ * Whether the action can create, show, copy or rotate a key, password, token
+ * or other secret, or hand one to the app (its catalog entry lists where).
+ */
+export declare function appActionHandlesSecrets(entry: ActionCatalogEntry): boolean;
+/**
+ * Whether this call of the action carries a secret: the action returns or
+ * stores one whatever it is given (a response field or a route), or this
+ * call's body fills a request field that holds one ("headers" when creating a
+ * chat with MCP servers; creating it without them carries none). Without full
+ * access the chat route never runs such a call: one click would put a lasting
+ * secret into the conversation and the model provider's logs. The person
+ * does it in the app instead.
+ */
+export declare function appActionCallCarriesSecrets(entry: ActionCatalogEntry, body: unknown): boolean;
+/** The same, for an admin_action_call's arguments; an unknown action is not one. */
+export declare function appActionCallHandlesSecrets(args: unknown): boolean;
+/**
+ * Whether this admin_action_call creates or updates a vault item. Its body is
+ * kept in the vault itself, so secret references in it may become values.
+ */
+export declare function appActionCallStoresVaultItem(args: unknown): boolean;
+/**
+ * Calls `visit` on each filled request field of this admin_action_call's body
+ * that its action marks as secret (a provider API key, an MCP server's
+ * headers), in catalog order, and returns the arguments with each field
+ * replaced by what `visit` returned. Only these fields take a secret from the
+ * caller; response and route fields don't. Arguments that are not an object,
+ * an unknown action, or a call without such fields come back unchanged.
+ */
+export declare function mapAppActionCallSecretInputs(args: unknown, visit: (value: unknown) => unknown): unknown;
+/** The values `mapAppActionCallSecretInputs` visits, in order. */
+export declare function appActionCallSecretInputs(args: unknown): unknown[];
+/**
+ * The question the person answers before a change runs, in plain words, from
+ * the action and its checked arguments; never text the agent wrote. `here` is
+ * the chat asking, so "this chat" and "this workspace" are said only when the
+ * call targets exactly them.
+ */
+export declare function appActionConfirmationTitle(args: unknown, here: {
+    workspaceId: string;
+    sessionId: string;
+}): string;