@cynodia/axiom-agent-api 0.8.1-alpha.1 → 0.9.0-alpha.1

package/dist/queries.d.ts

@@ -1,4 +1,4 @@
-import type { ActionDef, AnyNode, ApplicationGraph, ConstraintDef, EdgeKind, EventDef, Expression, ExpressionDef, FieldId, FormNode, GraphEdge, IntegrationDef, IntegrationOperationDef, Location, NodeId, StateDef, TransitionConstraintDef, TriggerDef, UINode, ViewNode } from '@cynodia/axiom-core';
+import type { ActionDef, AnyNode, ApplicationGraph, ConstraintDef, EdgeKind, EventDef, Expression, ExpressionDef, FieldId, FormNode, GraphEdge, IntegrationDef, IntegrationOperationDef, Location, NodeId, StateDef, StorageDef, SubscriptionDef, TransitionConstraintDef, TriggerDef, UINode, ViewNode } from '@cynodia/axiom-core';
 export interface SubgraphRequest {
     root: NodeId;
     depth?: number;
@@ -120,8 +120,60 @@ export declare class GraphQueries {
     };
     /** Triggers that fire on a schedule rather than on an event or a lifecycle moment. */
     getTimedTriggers(): TriggerDef[];
-    /** Events at least one trigger reacts to — the external/internal facts this application listens for. */
+    /**
+     * Events at least one trigger reacts to — the internal/external facts this application
+     * listens for.
+     *
+     * This is a **graph-static** query: it answers "which `EventDef`s have a `TriggerDef`
+     * bound to them", not "which webhook deliveries has this server received". An event
+     * returned here may be dispatched by a verified external webhook, by an effect's
+     * `succeededEventId`/`failedEventId`, or by any other internal source — "webhook-ness" is
+     * not a property the graph records, so a name implying it overstates what this answers
+     * (spec 8.2 §34-35).
+     */
+    getTriggeredEvents(): EventDef[];
+    /**
+     * @deprecated Renamed to {@link getTriggeredEvents} (spec 8.2 §34-36): this answers
+     * "which events have a trigger bound to them", not "which webhook deliveries were
+     * received" — the two are not the same, since the same query covers effect-outcome
+     * events too. Kept as an alias for backward compatibility; new code should call
+     * `getTriggeredEvents()` directly.
+     */
     getWebhookEvents(): EventDef[];
+    /** Every long-lived external event source this application declares. */
+    listSubscriptions(): SubscriptionDef[];
+    /** The subscriptions an integration's adapter is responsible for maintaining. */
+    getSubscriptionsForIntegration(integrationId: NodeId): SubscriptionDef[];
+    /** The `EventDef` a subscription's deliveries become. */
+    getEventForSubscription(subscriptionId: NodeId): EventDef | undefined;
+    /**
+     * Every action a delivery on this subscription can reach, following its event through the
+     * triggers bound to it. The answer to "what can this feed actually change" without
+     * walking the graph by hand.
+     */
+    getActionsReachableFromSubscription(subscriptionId: NodeId): ActionDef[];
+    /**
+     * Every way the outside world can reach this application, in one answer: the integrations
+     * it calls, the operations it calls on them, the live sources it listens to, the events
+     * those deliver, and the object stores it reads or writes.
+     *
+     * Graph-static, like every other query here — it says what the application *can* do, not
+     * what any running authority has done.
+     */
+    getExternalEventSources(): {
+        subscriptions: SubscriptionDef[];
+        events: EventDef[];
+        integrations: IntegrationDef[];
+    };
+    /** Every object store this application declares. */
+    listStorages(): StorageDef[];
+    /** Actions that read from, commit into or delete from this store. */
+    getActionsUsingStorage(storageId: NodeId): ActionDef[];
+    /**
+     * Stores that would serve nothing and accept nothing, because they declare no access
+     * rule. A missing rule is refusal, so this reports dead capability rather than a hole.
+     */
+    getStoragesWithoutAccessRules(): StorageDef[];
     /** Whether an ordinary client `InvokeRequest` may name this action at all. */
     isClientInvocable(actionId: NodeId): boolean;
     /** Whether this action accepts only trigger-, event- or effect-outcome-originated calls. */

package/dist/queries.js

@@ -394,14 +394,99 @@ export class GraphQueries {
             .getNodesByKind('trigger')
             .filter((trigger) => trigger.when.kind === 'interval' || trigger.when.kind === 'delay');
     }
-    /** Events at least one trigger reacts to — the external/internal facts this application listens for. */
-    getWebhookEvents() {
+    /**
+     * Events at least one trigger reacts to — the internal/external facts this application
+     * listens for.
+     *
+     * This is a **graph-static** query: it answers "which `EventDef`s have a `TriggerDef`
+     * bound to them", not "which webhook deliveries has this server received". An event
+     * returned here may be dispatched by a verified external webhook, by an effect's
+     * `succeededEventId`/`failedEventId`, or by any other internal source — "webhook-ness" is
+     * not a property the graph records, so a name implying it overstates what this answers
+     * (spec 8.2 §34-35).
+     */
+    getTriggeredEvents() {
         const referenced = new Set(this.graph
             .getNodesByKind('trigger')
             .filter((trigger) => trigger.when.kind === 'event')
             .map((trigger) => trigger.when.eventId));
         return this.graph.getNodesByKind('event').filter((event) => referenced.has(event.id));
     }
+    /**
+     * @deprecated Renamed to {@link getTriggeredEvents} (spec 8.2 §34-36): this answers
+     * "which events have a trigger bound to them", not "which webhook deliveries were
+     * received" — the two are not the same, since the same query covers effect-outcome
+     * events too. Kept as an alias for backward compatibility; new code should call
+     * `getTriggeredEvents()` directly.
+     */
+    getWebhookEvents() {
+        return this.getTriggeredEvents();
+    }
+    // -------------------------------------------- subscriptions and object storage
+    /** Every long-lived external event source this application declares. */
+    listSubscriptions() {
+        return this.graph.getNodesByKind('subscription');
+    }
+    /** The subscriptions an integration's adapter is responsible for maintaining. */
+    getSubscriptionsForIntegration(integrationId) {
+        return this.listSubscriptions().filter((subscription) => subscription.integrationId === integrationId);
+    }
+    /** The `EventDef` a subscription's deliveries become. */
+    getEventForSubscription(subscriptionId) {
+        const subscription = this.graph.getNode(subscriptionId);
+        if (subscription?.kind !== 'subscription') {
+            return undefined;
+        }
+        const event = this.graph.getNode(subscription.eventId);
+        return event?.kind === 'event' ? event : undefined;
+    }
+    /**
+     * Every action a delivery on this subscription can reach, following its event through the
+     * triggers bound to it. The answer to "what can this feed actually change" without
+     * walking the graph by hand.
+     */
+    getActionsReachableFromSubscription(subscriptionId) {
+        const event = this.getEventForSubscription(subscriptionId);
+        return event ? this.getActionsTriggeredByEvent(event.id) : [];
+    }
+    /**
+     * Every way the outside world can reach this application, in one answer: the integrations
+     * it calls, the operations it calls on them, the live sources it listens to, the events
+     * those deliver, and the object stores it reads or writes.
+     *
+     * Graph-static, like every other query here — it says what the application *can* do, not
+     * what any running authority has done.
+     */
+    getExternalEventSources() {
+        const subscriptions = this.listSubscriptions();
+        const eventIds = new Set(subscriptions.map((subscription) => subscription.eventId));
+        const integrationIds = new Set(subscriptions.map((subscription) => subscription.integrationId));
+        return {
+            subscriptions,
+            events: this.graph.getNodesByKind('event').filter((event) => eventIds.has(event.id)),
+            integrations: this.listIntegrations().filter((integration) => integrationIds.has(integration.id)),
+        };
+    }
+    /** Every object store this application declares. */
+    listStorages() {
+        return this.graph.getNodesByKind('storage');
+    }
+    /** Actions that read from, commit into or delete from this store. */
+    getActionsUsingStorage(storageId) {
+        return this.graph
+            .getNodesByKind('action')
+            .filter((action) => (action.operations ?? []).some((operation) => (operation.kind === 'blob-metadata' ||
+            operation.kind === 'blob-commit' ||
+            operation.kind === 'blob-delete') &&
+            operation.storageId === storageId));
+    }
+    /**
+     * Stores that would serve nothing and accept nothing, because they declare no access
+     * rule. A missing rule is refusal, so this reports dead capability rather than a hole.
+     */
+    getStoragesWithoutAccessRules() {
+        return this.listStorages().filter((storage) => !storage.readAuthorization && !storage.uploadAuthorization);
+    }
     /** Whether an ordinary client `InvokeRequest` may name this action at all. */
     isClientInvocable(actionId) {
         const action = this.graph.getNode(actionId);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cynodia/axiom-agent-api",
-  "version": "0.8.1-alpha.1",
+  "version": "0.9.0-alpha.1",
   "description": "Semantic queries and transactional graph transformations for AI agents.",
   "license": "MIT",
   "author": "AskTech AS",
@@ -31,7 +31,7 @@
     }
   },
   "dependencies": {
-    "@cynodia/axiom-core": "0.8.1-alpha.1"
+    "@cynodia/axiom-core": "0.9.0-alpha.1"
   },
   "scripts": {
     "build": "tsc -b tsconfig.json tsconfig.test.json",