@electric-ax/agents-server 0.4.6 → 0.4.9

package/dist/index.d.cts

@@ -187,7 +187,7 @@ import * as drizzle_orm_pg_core238 from "drizzle-orm/pg-core";
 import * as drizzle_orm_pg_core239 from "drizzle-orm/pg-core";
 import * as drizzle_orm73 from "drizzle-orm";
 import * as drizzle_orm74 from "drizzle-orm";
-import { EntityTags, WebhookNotification, WebhookSignatureVerifierConfig } from "@electric-ax/agents-runtime";
+import { EntityTags, EventSourceBucket, EventSourceContract, EventSourceContract as EventSourceContract$1, EventSourceFilter, EventSourceSubscription, EventSourceSubscription as EventSourceSubscription$1, EventSourceSubscriptionInput, SubscriptionLifetime, WebhookNotification, WebhookSignatureVerifierConfig } from "@electric-ax/agents-runtime";
 import "@sinclair/typebox";
 import { MaybePromise } from "@durable-streams/client";
 import { AutoRouterType, IRequest } from "itty-router";
@@ -3226,7 +3226,10 @@ interface Principal {
 type WakeNotification = WebhookNotification;
 type RequestPrincipal = Principal;
 type AuthenticateRequest = (request: Request) => Promise<Principal | null> | Principal | null;
-type EntityStatus = `spawning` | `running` | `idle` | `stopped`;
+type EntityStatus = `spawning` | `running` | `idle` | `paused` | `stopping` | `stopped` | `killed`;
+declare const ENTITY_SIGNALS: readonly ["SIGINT", "SIGHUP", "SIGTERM", "SIGKILL", "SIGSTOP", "SIGCONT", "SIGUSR"];
+type EntitySignal = (typeof ENTITY_SIGNALS)[number];
+declare function assertEntityStatus(s: string): EntityStatus;
 type DispatchTarget = {
   type: `webhook`;
   url: string;
@@ -3353,6 +3356,10 @@ interface ConsumerClaim {
   acked_streams?: Array<SourceStreamOffset>;
   updated_at: string;
 }
+declare function assertEntitySignal(s: string): EntitySignal;
+declare function isTerminalEntityStatus(status: EntityStatus): boolean;
+declare function rejectsNormalWrites(status: EntityStatus): boolean;
+declare function expectedSignalStatus(status: EntityStatus, signal: EntitySignal): EntityStatus;
 interface ElectricAgentsEntity {
   url: string;
   type: string;
@@ -3375,7 +3382,26 @@ interface ElectricAgentsEntity {
   updated_at: number;
 }
 /** Public-facing entity — internal fields stripped. Standalone type so new internal fields don't silently leak. */
-
+interface PublicElectricAgentsEntity {
+  url: string;
+  type: string;
+  status: EntityStatus;
+  streams: {
+    main: string;
+    error: string;
+  };
+  dispatch_policy?: DispatchPolicy;
+  tags: Record<string, string>;
+  spawn_args?: Record<string, unknown>;
+  parent?: string;
+  created_by?: string;
+  created_at: number;
+  updated_at: number;
+}
+/** Entity row as stored in Postgres / returned by Electric shapes (no derived `streams` field). */
+type ElectricAgentsEntityRow = Omit<PublicElectricAgentsEntity, `streams`>;
+/** Strip internal fields (write_token, subscription_id) from an entity. */
+declare function toPublicEntity(entity: ElectricAgentsEntity): PublicElectricAgentsEntity;
 interface ElectricAgentsEntityType {
   name: string;
   description: string;
@@ -3415,6 +3441,7 @@ interface TypedSpawnRequest {
     debounceMs?: number;
     timeoutMs?: number;
     includeResponse?: boolean;
+    manifestKey?: string;
   };
 }
 interface SendRequest {
@@ -3425,9 +3452,27 @@ interface SendRequest {
   mode?: `immediate` | `queued` | `paused` | `steer`;
   position?: string;
 }
+interface SignalRequest {
+  signal: EntitySignal;
+  reason?: string;
+  payload?: unknown;
+}
+interface SignalResponse {
+  url: string;
+  signal: EntitySignal;
+  previous_state: EntityStatus;
+  new_state: EntityStatus;
+  created_at: number;
+  txid: number;
+}
 interface SetTagRequest {
   value: string;
 }
+interface EntityListFilter {
+  type?: string;
+  status?: EntityStatus;
+  created_by?: string;
+}
 
 //#endregion
 //#region src/entity-registry.d.ts
@@ -3559,7 +3604,8 @@ declare class PostgresRegistry {
     total: number;
   }>;
   updateStatus(entityUrl: string, status: EntityStatus): Promise<void>;
-  updateStatusWithTxid(entityUrl: string, status: EntityStatus): Promise<number>;
+  updateStatusWithTxid(entityUrl: string, status: EntityStatus): Promise<number | null>;
+  touchEntityWithTxid(entityUrl: string): Promise<number | null>;
   setEntityTag(url: string, key: string, value: string): Promise<{
     entity: ElectricAgentsEntity | null;
     changed: boolean;
@@ -4160,6 +4206,18 @@ declare class EntityManager {
   }): Promise<{
     txid: string;
   }>;
+  upsertEventSourceSubscription(entityUrl: string, req: {
+    subscription: EventSourceSubscription$1;
+    manifest: Record<string, unknown>;
+  }): Promise<{
+    txid: string;
+    subscription: EventSourceSubscription$1;
+  }>;
+  deleteEventSourceSubscription(entityUrl: string, req: {
+    id: string;
+  }): Promise<{
+    txid: string;
+  }>;
   /**
    * Register a wake subscription from a subscriber to a source entity.
    */
@@ -4193,9 +4251,12 @@ declare class EntityManager {
    */
   private extractRunResponse;
   private buildWakeMessage;
+  signal(entityUrl: string, req: SignalRequest): Promise<SignalResponse>;
   kill(entityUrl: string): Promise<{
     txid: number;
   }>;
+  private serverHandlingForSignal;
+  private appendSignalEvent;
   validateWriteEvent(entity: ElectricAgentsEntity, event: Record<string, unknown>): Promise<{
     code: string;
     message: string;
@@ -4406,6 +4467,10 @@ declare function webhookSigningMetadata(signer: WebhookSigner, streamRootUrl: st
 
 //#endregion
 //#region src/routing/context.d.ts
+interface EventSourceCatalog {
+  listEventSources: () => Array<EventSourceContract$1> | Promise<Array<EventSourceContract$1>>;
+  getEventSource: (sourceKey: string) => EventSourceContract$1 | undefined | Promise<EventSourceContract$1 | undefined>;
+}
 /**
  * Per-request tenant context passed through every router and handler.
  *
@@ -4432,6 +4497,8 @@ interface TenantContext {
   streamClient: StreamClient;
   runtime: ElectricAgentsTenantRuntime;
   entityBridgeManager: EntityBridgeCoordinator;
+  eventSources?: EventSourceCatalog;
+  ensureEventSourceWakeSource?: (sourceUrl: string) => Promise<void> | void;
   isShuttingDown: () => boolean;
 }
 
@@ -4451,4 +4518,4 @@ declare class UnregisteredTenantError extends Error {
 declare function isUnregisteredTenantError(error: unknown): error is UnregisteredTenantError;
 
 //#endregion
-export { AgentsHost, AgentsHostOptions, AgentsHostTenantConfig, AgentsHostTenantRuntime, AuthenticateRequest, ConsumerClaim, DEFAULT_TENANT_ID, DispatchPolicy, DispatchTarget, DrizzleDB, DurableStreamsBearerProvider, DurableStreamsRoutingAdapter, DurableStreamsRoutingInput, Ed25519WebhookSignerOptions, ElectricAgentsRunner, ElectricAgentsUser, EntityBridgeCoordinator, EntityDispatchState, GlobalRoutes, PgClient, Principal, PrincipalKind, PublicWakeNotification, RegisterRunnerRequest, RequestPrincipal, RunnerAdminStatus, RunnerHeartbeatRequest, RunnerKind, RunnerLiveness, SourceStreamOffset, StreamClient, StreamClientOptions, SubscriptionClaimResponse, SubscriptionCreateInput, SubscriptionResponse, SubscriptionStreamInfo, TenantContext, UnregisteredTenantError, WakeNotificationRow, WebhookJwks, WebhookPublicJwk, WebhookSigner, WebhookSigningKeyInput, WebhookSigningMetadata, createDb, createEd25519WebhookSigner, getDefaultWebhookSigner, globalRouter, isUnregisteredTenantError, pathPrefixedSingleTenantDurableStreamsRoutingAdapter, runMigrations, streamRootDurableStreamsRoutingAdapter, tenantRootDurableStreamsRoutingAdapter, webhookSigningMetadata };
+export { AgentsHost, AgentsHostOptions, AgentsHostTenantConfig, AgentsHostTenantRuntime, AuthenticateRequest, ConsumerClaim, DEFAULT_TENANT_ID, DispatchPolicy, DispatchTarget, DrizzleDB, DurableStreamsBearerProvider, DurableStreamsRoutingAdapter, DurableStreamsRoutingInput, Ed25519WebhookSignerOptions, ElectricAgentsEntity, ElectricAgentsEntityRow, ElectricAgentsEntityType, ElectricAgentsRunner, ElectricAgentsUser, EntityBridgeCoordinator, EntityDispatchState, EntityListFilter, EntitySignal, EntityStatus, EventSourceBucket, EventSourceCatalog, EventSourceContract, EventSourceFilter, EventSourceSubscription, EventSourceSubscriptionInput, GlobalRoutes, PgClient, Principal, PrincipalKind, PublicElectricAgentsEntity, PublicWakeNotification, RegisterEntityTypeRequest, RegisterRunnerRequest, RequestPrincipal, RunnerAdminStatus, RunnerHeartbeatRequest, RunnerKind, RunnerLiveness, SendRequest, SignalRequest, SignalResponse, SourceStreamOffset, StreamClient, StreamClientOptions, SubscriptionClaimResponse, SubscriptionCreateInput, SubscriptionLifetime, SubscriptionResponse, SubscriptionStreamInfo, TenantContext, TypedSpawnRequest, UnregisteredTenantError, WakeNotificationRow, WebhookJwks, WebhookPublicJwk, WebhookSigner, WebhookSigningKeyInput, WebhookSigningMetadata, assertEntitySignal, assertEntityStatus, createDb, createEd25519WebhookSigner, expectedSignalStatus, getDefaultWebhookSigner, globalRouter, isTerminalEntityStatus, isUnregisteredTenantError, pathPrefixedSingleTenantDurableStreamsRoutingAdapter, rejectsNormalWrites, runMigrations, streamRootDurableStreamsRoutingAdapter, tenantRootDurableStreamsRoutingAdapter, toPublicEntity, webhookSigningMetadata };

package/dist/index.d.ts

@@ -189,7 +189,7 @@ import * as drizzle_orm_pg_core237 from "drizzle-orm/pg-core";
 import * as drizzle_orm_pg_core238 from "drizzle-orm/pg-core";
 import * as drizzle_orm_pg_core239 from "drizzle-orm/pg-core";
 import { JsonWebKey, KeyObject } from "node:crypto";
-import { EntityTags, WebhookNotification, WebhookSignatureVerifierConfig } from "@electric-ax/agents-runtime";
+import { EntityTags, EventSourceBucket, EventSourceContract, EventSourceContract as EventSourceContract$1, EventSourceFilter, EventSourceSubscription, EventSourceSubscription as EventSourceSubscription$1, EventSourceSubscriptionInput, SubscriptionLifetime, WebhookNotification, WebhookSignatureVerifierConfig } from "@electric-ax/agents-runtime";
 import { MaybePromise } from "@durable-streams/client";
 import "@sinclair/typebox";
 import { AutoRouterType, IRequest } from "itty-router";
@@ -3227,7 +3227,10 @@ interface Principal {
 type WakeNotification = WebhookNotification;
 type RequestPrincipal = Principal;
 type AuthenticateRequest = (request: Request) => Promise<Principal | null> | Principal | null;
-type EntityStatus = `spawning` | `running` | `idle` | `stopped`;
+type EntityStatus = `spawning` | `running` | `idle` | `paused` | `stopping` | `stopped` | `killed`;
+declare const ENTITY_SIGNALS: readonly ["SIGINT", "SIGHUP", "SIGTERM", "SIGKILL", "SIGSTOP", "SIGCONT", "SIGUSR"];
+type EntitySignal = (typeof ENTITY_SIGNALS)[number];
+declare function assertEntityStatus(s: string): EntityStatus;
 type DispatchTarget = {
   type: `webhook`;
   url: string;
@@ -3354,6 +3357,10 @@ interface ConsumerClaim {
   acked_streams?: Array<SourceStreamOffset>;
   updated_at: string;
 }
+declare function assertEntitySignal(s: string): EntitySignal;
+declare function isTerminalEntityStatus(status: EntityStatus): boolean;
+declare function rejectsNormalWrites(status: EntityStatus): boolean;
+declare function expectedSignalStatus(status: EntityStatus, signal: EntitySignal): EntityStatus;
 interface ElectricAgentsEntity {
   url: string;
   type: string;
@@ -3376,7 +3383,26 @@ interface ElectricAgentsEntity {
   updated_at: number;
 }
 /** Public-facing entity — internal fields stripped. Standalone type so new internal fields don't silently leak. */
-
+interface PublicElectricAgentsEntity {
+  url: string;
+  type: string;
+  status: EntityStatus;
+  streams: {
+    main: string;
+    error: string;
+  };
+  dispatch_policy?: DispatchPolicy;
+  tags: Record<string, string>;
+  spawn_args?: Record<string, unknown>;
+  parent?: string;
+  created_by?: string;
+  created_at: number;
+  updated_at: number;
+}
+/** Entity row as stored in Postgres / returned by Electric shapes (no derived `streams` field). */
+type ElectricAgentsEntityRow = Omit<PublicElectricAgentsEntity, `streams`>;
+/** Strip internal fields (write_token, subscription_id) from an entity. */
+declare function toPublicEntity(entity: ElectricAgentsEntity): PublicElectricAgentsEntity;
 interface ElectricAgentsEntityType {
   name: string;
   description: string;
@@ -3416,6 +3442,7 @@ interface TypedSpawnRequest {
     debounceMs?: number;
     timeoutMs?: number;
     includeResponse?: boolean;
+    manifestKey?: string;
   };
 }
 interface SendRequest {
@@ -3426,9 +3453,27 @@ interface SendRequest {
   mode?: `immediate` | `queued` | `paused` | `steer`;
   position?: string;
 }
+interface SignalRequest {
+  signal: EntitySignal;
+  reason?: string;
+  payload?: unknown;
+}
+interface SignalResponse {
+  url: string;
+  signal: EntitySignal;
+  previous_state: EntityStatus;
+  new_state: EntityStatus;
+  created_at: number;
+  txid: number;
+}
 interface SetTagRequest {
   value: string;
 }
+interface EntityListFilter {
+  type?: string;
+  status?: EntityStatus;
+  created_by?: string;
+}
 
 //#endregion
 //#region src/entity-registry.d.ts
@@ -3560,7 +3605,8 @@ declare class PostgresRegistry {
     total: number;
   }>;
   updateStatus(entityUrl: string, status: EntityStatus): Promise<void>;
-  updateStatusWithTxid(entityUrl: string, status: EntityStatus): Promise<number>;
+  updateStatusWithTxid(entityUrl: string, status: EntityStatus): Promise<number | null>;
+  touchEntityWithTxid(entityUrl: string): Promise<number | null>;
   setEntityTag(url: string, key: string, value: string): Promise<{
     entity: ElectricAgentsEntity | null;
     changed: boolean;
@@ -4161,6 +4207,18 @@ declare class EntityManager {
   }): Promise<{
     txid: string;
   }>;
+  upsertEventSourceSubscription(entityUrl: string, req: {
+    subscription: EventSourceSubscription$1;
+    manifest: Record<string, unknown>;
+  }): Promise<{
+    txid: string;
+    subscription: EventSourceSubscription$1;
+  }>;
+  deleteEventSourceSubscription(entityUrl: string, req: {
+    id: string;
+  }): Promise<{
+    txid: string;
+  }>;
   /**
    * Register a wake subscription from a subscriber to a source entity.
    */
@@ -4194,9 +4252,12 @@ declare class EntityManager {
    */
   private extractRunResponse;
   private buildWakeMessage;
+  signal(entityUrl: string, req: SignalRequest): Promise<SignalResponse>;
   kill(entityUrl: string): Promise<{
     txid: number;
   }>;
+  private serverHandlingForSignal;
+  private appendSignalEvent;
   validateWriteEvent(entity: ElectricAgentsEntity, event: Record<string, unknown>): Promise<{
     code: string;
     message: string;
@@ -4407,6 +4468,10 @@ declare function webhookSigningMetadata(signer: WebhookSigner, streamRootUrl: st
 
 //#endregion
 //#region src/routing/context.d.ts
+interface EventSourceCatalog {
+  listEventSources: () => Array<EventSourceContract$1> | Promise<Array<EventSourceContract$1>>;
+  getEventSource: (sourceKey: string) => EventSourceContract$1 | undefined | Promise<EventSourceContract$1 | undefined>;
+}
 /**
  * Per-request tenant context passed through every router and handler.
  *
@@ -4433,6 +4498,8 @@ interface TenantContext {
   streamClient: StreamClient;
   runtime: ElectricAgentsTenantRuntime;
   entityBridgeManager: EntityBridgeCoordinator;
+  eventSources?: EventSourceCatalog;
+  ensureEventSourceWakeSource?: (sourceUrl: string) => Promise<void> | void;
   isShuttingDown: () => boolean;
 }
 
@@ -4452,4 +4519,4 @@ declare class UnregisteredTenantError extends Error {
 declare function isUnregisteredTenantError(error: unknown): error is UnregisteredTenantError;
 
 //#endregion
-export { AgentsHost, AgentsHostOptions, AgentsHostTenantConfig, AgentsHostTenantRuntime, AuthenticateRequest, ConsumerClaim, DEFAULT_TENANT_ID, DispatchPolicy, DispatchTarget, DrizzleDB, DurableStreamsBearerProvider, DurableStreamsRoutingAdapter, DurableStreamsRoutingInput, Ed25519WebhookSignerOptions, ElectricAgentsRunner, ElectricAgentsUser, EntityBridgeCoordinator, EntityDispatchState, GlobalRoutes, PgClient, Principal, PrincipalKind, PublicWakeNotification, RegisterRunnerRequest, RequestPrincipal, RunnerAdminStatus, RunnerHeartbeatRequest, RunnerKind, RunnerLiveness, SourceStreamOffset, StreamClient, StreamClientOptions, SubscriptionClaimResponse, SubscriptionCreateInput, SubscriptionResponse, SubscriptionStreamInfo, TenantContext, UnregisteredTenantError, WakeNotificationRow, WebhookJwks, WebhookPublicJwk, WebhookSigner, WebhookSigningKeyInput, WebhookSigningMetadata, createDb, createEd25519WebhookSigner, getDefaultWebhookSigner, globalRouter, isUnregisteredTenantError, pathPrefixedSingleTenantDurableStreamsRoutingAdapter, runMigrations, streamRootDurableStreamsRoutingAdapter, tenantRootDurableStreamsRoutingAdapter, webhookSigningMetadata };
+export { AgentsHost, AgentsHostOptions, AgentsHostTenantConfig, AgentsHostTenantRuntime, AuthenticateRequest, ConsumerClaim, DEFAULT_TENANT_ID, DispatchPolicy, DispatchTarget, DrizzleDB, DurableStreamsBearerProvider, DurableStreamsRoutingAdapter, DurableStreamsRoutingInput, Ed25519WebhookSignerOptions, ElectricAgentsEntity, ElectricAgentsEntityRow, ElectricAgentsEntityType, ElectricAgentsRunner, ElectricAgentsUser, EntityBridgeCoordinator, EntityDispatchState, EntityListFilter, EntitySignal, EntityStatus, EventSourceBucket, EventSourceCatalog, EventSourceContract, EventSourceFilter, EventSourceSubscription, EventSourceSubscriptionInput, GlobalRoutes, PgClient, Principal, PrincipalKind, PublicElectricAgentsEntity, PublicWakeNotification, RegisterEntityTypeRequest, RegisterRunnerRequest, RequestPrincipal, RunnerAdminStatus, RunnerHeartbeatRequest, RunnerKind, RunnerLiveness, SendRequest, SignalRequest, SignalResponse, SourceStreamOffset, StreamClient, StreamClientOptions, SubscriptionClaimResponse, SubscriptionCreateInput, SubscriptionLifetime, SubscriptionResponse, SubscriptionStreamInfo, TenantContext, TypedSpawnRequest, UnregisteredTenantError, WakeNotificationRow, WebhookJwks, WebhookPublicJwk, WebhookSigner, WebhookSigningKeyInput, WebhookSigningMetadata, assertEntitySignal, assertEntityStatus, createDb, createEd25519WebhookSigner, expectedSignalStatus, getDefaultWebhookSigner, globalRouter, isTerminalEntityStatus, isUnregisteredTenantError, pathPrefixedSingleTenantDurableStreamsRoutingAdapter, rejectsNormalWrites, runMigrations, streamRootDurableStreamsRoutingAdapter, tenantRootDurableStreamsRoutingAdapter, toPublicEntity, webhookSigningMetadata };