@vertesia/common 1.4.0 → 1.5.0-dev.20260713.113008Z

package/src/project.ts

@@ -269,6 +269,39 @@ export const BrowserUseProjectConfigurationSchema: JSONSchemaType<BrowserUseProj
 export type ProjectSearchTier = 'standard' | 'performance';
 export type ElasticsearchBackend = 'serverless' | 'hosted';
 
+export interface ProjectIntakeConfiguration {
+    /**
+     * Generate table-of-content sections during standard document intake.
+     * Defaults to false.
+     */
+    generate_toc?: boolean;
+
+    /**
+     * Skip table-of-content generation when the document text exceeds this many characters.
+     * Avoids sending very large documents through the TOC interactions. Unset means no limit.
+     */
+    generate_toc_max_size?: number;
+
+    /**
+     * Select or assign a content type during standard intake.
+     * Defaults to true.
+     */
+    generate_content_type?: boolean;
+
+    /**
+     * Extract document properties after content type assignment.
+     * Defaults to true.
+     */
+    generate_properties?: boolean;
+
+    /**
+     * Default content type assigned during intake when type selection finds no matching type.
+     * A type id resolvable in this project (a stored `oid:` type, an `app:` type, or a `sys:` type).
+     * Defaults to the platform `sys:GenericDocument` when unset.
+     */
+    default_content_type?: string;
+}
+
 export interface ProjectConfiguration {
     human_context?: string;
 
@@ -321,6 +354,11 @@ export interface ProjectConfiguration {
         backend?: ElasticsearchBackend;
     };
 
+    /**
+     * Standard content intake behavior.
+     */
+    intake?: ProjectIntakeConfiguration;
+
     /**
      * Primary language for full-text search analysis.
      * ISO 639-1 code (e.g., 'en', 'fr', 'ja', 'de').

package/src/prompt.ts

@@ -46,6 +46,7 @@ export interface PromptTemplateRef {
     version: number;
     status: PromptStatus;
     content_type?: TemplateType;
+    tags?: string[];
     created_at: Date;
     updated_at: Date;
 }

package/src/query.ts

@@ -64,6 +64,7 @@ export interface ObjectTypeSearchQuery extends SimpleSearchQuery {
 
 export interface PromptSearchQuery extends SimpleSearchQuery {
     role?: string;
+    tags?: string[];
     matchInteractions?: boolean;
 }
 

package/src/rate-limiter.ts

@@ -32,3 +32,81 @@ export interface RateLimiterStatus {
 
 // Always return an array for consistency
 export type RateLimiterStatusResponse = RateLimiterStatus[];
+
+/**
+ * A caller's own quota standing (GET /api/v1/quota/standing) — "where am I".
+ * API rate limits are genuinely per-tenant; workflow admission and the LLM limiter are
+ * global/discovered, so they are reported as posture, not per-tenant numbers.
+ */
+export interface QuotaStandingWindow {
+    /** Effective limit for this window (after effective account tier + per-tenant override). */
+    limit: number;
+    /** Requests used in the current window. */
+    used: number;
+    /** Requests remaining (max(0, limit - used)). */
+    remaining: number;
+    window_ms: number;
+}
+
+export interface QuotaStandingResource {
+    resource: string;
+    name: string;
+    burst: QuotaStandingWindow;
+    quota: QuotaStandingWindow;
+}
+
+export interface QuotaStandingAdmissionClass {
+    /** Workflow class (e.g. ExecuteConversationWorkflow). */
+    class: string;
+    /** This tenant's currently active (leased) slots for the class. */
+    tenant_active: number;
+}
+
+/**
+ * Effective quota tier name after account-level overrides and account-type derivation.
+ * Code-defined tier names are currently `QuotaTier`, but this remains a string because deployments
+ * can introduce quota tiers through configuration.
+ */
+export type QuotaEffectiveTier = string;
+
+export interface QuotaStandingResponse {
+    tenant_id: string;
+    /**
+     * False when the limiter store (Redis) was unavailable, so `api`/`admission` are empty because
+     * standing could not be read — NOT because there are no limits. Limiters fail open in this case.
+     */
+    available: boolean;
+    /** Deployment base tier (env QUOTA_BASE_TIER); `default` = the static limits stand. */
+    base_tier: string;
+    /**
+     * Tier used to compute the API limits below: explicit account `quota_tier`, else account_type
+     * derived tier, else `base_tier` when the account tier could not be resolved.
+     */
+    effective_tier: QuotaEffectiveTier;
+    /** Per-resource API rate-limit standing (effective limits + current usage). */
+    api: QuotaStandingResource[];
+    /**
+     * Workflow admission: per-tenant active slots per probed class. The budget itself is global and
+     * discovered (AIMD), not a per-tenant number — this is occupancy, not a limit.
+     */
+    admission: {
+        classes: QuotaStandingAdmissionClass[];
+        note: string;
+    };
+    /** The LLM interaction limiter is shared per environment/model, not per tenant. */
+    llm: {
+        note: string;
+    };
+}
+
+/**
+ * Lightweight per-account quota tier for the calling account — served by `GET /api/v1/quota/tier`.
+ * A cheap, cacheable read that lets another service (e.g. zeno-server's API rate limiter) resolve
+ * the caller's tier through studio-server instead of reaching into the account store directly.
+ * `tier` is the SAME value {@link QuotaStandingResponse.effective_tier} reports: the account's
+ * explicit `quota_tier`, else its account_type-derived tier, else the deployment base tier when the
+ * account tier cannot be resolved.
+ */
+export interface QuotaTierResponse {
+    tier: QuotaEffectiveTier;
+}

package/src/roles/types.ts

@@ -8,7 +8,7 @@ import type { Permission } from '../access-control.js';
  */
 
 /**
- * Kind of object a ContentSet's `resource_props` matches at query time. Used
+ * Kind of object a ResourceSet's `resource_props` matches at query time. Used
  * in `AceConditions.scope` (validated at runtime against this list) and as
  * the prefix in JWT `content_security` keys (e.g. `collection:read`).
  *

package/src/secrets.ts

@@ -3,6 +3,7 @@ import type {
     WebsiteCredentialRecord,
     WebsiteCredentialSecretInput,
 } from './browser-credentials.js';
+import type { EventCategory } from './platform-event.js';
 
 // First supported top-level secret kind. OAuth connector grants continue to use
 // the OAuth/MCP token flows and can be materialized later by tools that need them.
@@ -58,3 +59,71 @@ export interface UpdateSecretRequest {
     clear_totp?: boolean;
     clear_oauth?: boolean;
 }
+
+export interface EventWebhookSigningSecretRequest {
+    account_id?: string;
+    project_id: string;
+}
+
+export interface EventWebhookSigningSecretResponse {
+    subscription_id: string;
+    secret: string;
+    secret_label: string;
+}
+
+export interface SignEventWebhookRequest extends EventWebhookSigningSecretRequest {
+    delivery_id: string;
+    body: string;
+    event_id: string;
+    event_category: EventCategory;
+    action: string;
+    timestamp?: number;
+}
+
+export interface SignEventWebhookResponse {
+    headers: Record<string, string>;
+    timestamp: number;
+    signature: string;
+}
+
+export interface EventIngestSigningSecretRequest {
+    account_id?: string;
+    project_id: string;
+}
+
+export interface EventIngestSigningSecretResponse {
+    channel_id: string;
+    secret: string;
+    secret_label: string;
+}
+
+export interface VerifyEventIngestSignatureRequest extends EventIngestSigningSecretRequest {
+    /** Raw request body bytes (exactly as received) the sender signed. */
+    body: string;
+    /** Signature value from the request header. */
+    signature_header: string;
+    algorithm?: 'sha256' | 'sha1';
+    encoding?: 'hex' | 'base64';
+    /** Literal prefix to strip from the header value, e.g. `sha256=`. */
+    prefix?: string;
+}
+
+export interface VerifyEventIngestSignatureResponse {
+    valid: boolean;
+}
+
+export interface GithubInstallationTokenRequest {
+    account_id?: string;
+    project_id: string;
+    /** Numeric GitHub App installation id (from the trusted webhook payload, never agent-supplied). */
+    installation_id: string;
+    /** `owner/name` of the repo to scope the token to. Required — tokens are always repository-scoped. */
+    repo: string;
+}
+
+export interface GithubInstallationTokenResponse {
+    /** Short-lived, repository-scoped GitHub App installation token. */
+    token: string;
+    /** ISO-8601 expiry returned by GitHub, when available. */
+    expires_at?: string;
+}

package/src/store/agent-run.ts

@@ -20,6 +20,8 @@ import type {
     InteractionRef,
     RunSource,
 } from '../interaction.js';
+import type { EventRef } from '../platform-event.js';
+import type { ResourceRef } from '../refs.js';
 import type { AgentEvent } from '../workflow-analytics.js';
 import type { AgentToolApprovalMode } from './agent-approval.js';
 import type { ProcessDefinitionBody, ProcessState } from './process.js';
@@ -53,7 +55,7 @@ export type AgentRunArchiveState = 'none' | 'pending' | 'archiving' | 'complete'
 /**
  * How the agent run was created.
  */
-export type AgentRunType = 'api' | 'schedule';
+export type AgentRunType = 'api' | 'schedule' | 'event_subscription';
 
 /**
  * Internal discriminator key for documents stored in the agent_runs collection.
@@ -130,6 +132,12 @@ export interface RunBase {
     /** Schedule ID — set when this run was triggered by a Temporal schedule */
     schedule_id?: string;
 
+    /** Event subscription ID — set when this run was triggered by the event bus. */
+    event_subscription_id?: string;
+
+    /** Event reference — set when this run was triggered by the event bus. */
+    event_ref?: EventRef;
+
     /** Archive lifecycle state */
     archive_state?: AgentRunArchiveState;
 
@@ -235,6 +243,13 @@ export interface AgentRun<TData = Record<string, unknown>, TProperties = Record<
 
     interactionRef: InteractionRef;
 
+    /**
+     * Resolved environment reference (name resolved from `config.environment` id).
+     * Populated by the list endpoint; may be absent on other endpoints or when the id
+     * cannot be resolved, in which case consumers should fall back to `config.environment`.
+     */
+    environmentRef?: ResourceRef;
+
     // --- Lifecycle ---
 
     /** Current status of the agent run */
@@ -749,6 +764,12 @@ export interface AgentRunSearchHit {
     /** Schedule ID (if schedule-triggered) */
     schedule_id?: string;
 
+    /** Event subscription ID (if event-triggered) */
+    event_subscription_id?: string;
+
+    /** Event reference (if event-triggered) */
+    event_ref?: EventRef;
+
     /** How the run was created */
     source_type?: AgentRunType;
 

package/src/store/process-validation.test.ts

@@ -410,6 +410,68 @@ describe('process definition validation', () => {
         expect(result.errors).toContain('human_task node "review" is missing task');
     });
 
+    it('rejects human_task fields that use "id" instead of "name"', () => {
+        const definition = validDefinition();
+        definition.nodes.review.task = {
+            title: 'Review',
+            fields: [{ id: 'approved', type: 'boolean' } as unknown as { name: string; type: 'boolean' }],
+        };
+
+        const result = getProcessDefinitionValidationResult(definition);
+
+        expect(result.valid).toBe(false);
+        expect(result.errors).toContain(
+            'human_task node "review" task.fields[0].name must be a non-empty string (not "id")',
+        );
+    });
+
+    it('rejects human_task fields with an unsupported type', () => {
+        const definition = validDefinition();
+        definition.nodes.review.task = {
+            title: 'Review',
+            fields: [{ name: 'approved', type: 'date' } as unknown as { name: string; type: 'string' }],
+        };
+
+        const result = getProcessDefinitionValidationResult(definition);
+
+        expect(result.valid).toBe(false);
+        expect(result.errors).toContain(
+            'human_task node "review" task.fields[0].type must be one of string, number, boolean, select, text',
+        );
+    });
+
+    it('rejects select fields without options', () => {
+        const definition = validDefinition();
+        definition.nodes.review.task = {
+            title: 'Review',
+            fields: [{ name: 'decision', type: 'select' }],
+        };
+
+        const result = getProcessDefinitionValidationResult(definition);
+
+        expect(result.valid).toBe(false);
+        expect(result.errors).toContain(
+            'human_task node "review" task.fields[0] of type "select" requires a non-empty options[] array',
+        );
+    });
+
+    it('accepts human_task select fields with options', () => {
+        const definition = validDefinition();
+        definition.nodes.review.task = {
+            title: 'Review',
+            fields: [
+                {
+                    name: 'decision',
+                    type: 'select',
+                    options: ['approved', 'rejected'],
+                    required: true,
+                },
+            ],
+        };
+
+        expect(() => validateProcessDefinitionBody(definition)).not.toThrow();
+    });
+
     it('rejects overly deep guard rules', () => {
         const definition = validDefinition();
         let guard: Record<string, unknown> = { var: 'approved' };

package/src/store/process-validation.ts

@@ -113,6 +113,24 @@ function validateNodeDefinition(
             errors.push(`human_task node "${nodeId}" task title is missing`);
         } else if (!Array.isArray(node.task.fields)) {
             errors.push(`human_task node "${nodeId}" task fields must be an array`);
+        } else {
+            const allowedTypes = ['string', 'number', 'boolean', 'select', 'text'];
+            (node.task.fields as unknown[]).forEach((field, i) => {
+                const path = `human_task node "${nodeId}" task.fields[${i}]`;
+                if (!isRecord(field)) {
+                    errors.push(`${path} must be an object`);
+                    return;
+                }
+                if (typeof field.name !== 'string' || field.name.length === 0) {
+                    errors.push(`${path}.name must be a non-empty string (not "id")`);
+                }
+                if (typeof field.type !== 'string' || !allowedTypes.includes(field.type)) {
+                    errors.push(`${path}.type must be one of ${allowedTypes.join(', ')}`);
+                }
+                if (field.type === 'select' && !(Array.isArray(field.options) && field.options.length > 0)) {
+                    errors.push(`${path} of type "select" requires a non-empty options[] array`);
+                }
+            });
         }
     }
     if (node.type === 'tool') {