Runtime invocation and workers

The @galinum/server/communications export lets a host use the public communication handlers with its own credential storage and project services.

import {
  resolveOperation,
  authorizeOperation,
  invokeCommunication,
} from "@galinum/server/communications";

const operation = resolveOperation(request);
if (operation instanceof Response) return operation;
const grant = await authorizeOperation(operation, request, authenticateProject);
if (grant instanceof Response) return grant;
return invokeCommunication(operation, request, grant, servicesFor(grant.projectId));

authenticateProject verifies the actual request credential and returns a ProjectPrincipal: a projectId and credentials containing verified security schemes. A host can compare credential hashes without configuring plaintext self-host keys. Hosted-agent proofs must include their permitted operation IDs. The host remains responsible for authenticating credentials honestly. Operation security comes from OpenAPI. Alternatives use OR; schemes within an alternative use AND. Installation capability headers remain required and are independently checked against persisted installation scope by the public handlers. Resolution and authorization bind the operation to the original request, method, URL, and headers. Grants are opaque and consumed once. Do not copy them or change the request after resolution. Invocation rejects project mismatches before it reads the body or constructs handlers. CommunicationServices supplies the project ID, a narrow communication data transaction, installation store, push and in-app engines, business clock, and optional typed effects. Effects receive the same transaction executor as the product mutation. The shared handlers cover identify, events, in-app decisions and feedback, installations, push credentials, tests, dispatch, and inspection. Other management operations need their own handlers. Operator authority remains separate. createCommunicationHandler(services, authenticateProject) combines resolution, authorization, and invocation for one project.

Push admission

const progress = await push.runPass({
  maxUnits: 100,
  maxPages: 100,
  deadline: performance.now() + 40_000,
});

The optional campaignId restricts the pass to one campaign. Limits default to 100 units and 100 discovery pages, with no deadline. Both limits accept nonnegative safe integers. deadline is an absolute value on the execution clock; the default clock is performance.now. A custom clock must return finite values on the same monotonic time scale as the deadline. Business timestamps continue to use the engine’s business clock. A unit admits one recipient planning or reconciliation operation, or one complete dispatch operation. Dispatch includes reservation, provider work, and settlement. When a limit expires, the engine stops admitting new units. An admitted send finishes under its existing fence, even after the deadline. The budget does not guarantee a maximum process lifetime or abort provider requests. Progress reports admittedUnits, recipient and dispatch units, pages, stopped (unit_limit, page_limit, deadline, or null), and phase errors. Persisted planning cursors retain partial progress. Phase rotation lets repeated small passes reach planning, reconciliation, and dispatch. A campaign discovered at the page limit remains pending for a later pass. Discovery pages count campaign, recipient, reconciliation, and dispatch queries. Cursor bookkeeping consumes neither pages nor units. Zero page or unit limits perform no store work. A pass with no reported stop does not establish that all campaign work is complete. The self-host CLI uses this public pass for automatic scheduling. Its existing page-limited worker defaults remain in place. Hosts can choose smaller budgets and invoke further passes; retry eligibility, expiration, and recovery remain public product behavior.

Trusted-session inspection reads

A server host can authorize push inspection after authenticating its own operator session. authorizeManagementRead accepts only a resolved GET inspectPushCampaign. Its callback returns { projectId, operationId: "inspectPushCampaign" }, a denial Response, or null for absent/revoked access. It does not accept credential proof or authenticate an external header.

import {
  resolveOperation,
  authorizeManagementRead,
  invokeCommunication,
} from "@galinum/server/communications";

const operation = resolveOperation(request);
if (operation instanceof Response) return operation;
const grant = await authorizeManagementRead(operation, request, async () => {
  const session = await authenticateCurrentSession();
  if (!session || !await canReadProject(session, selectedProjectId)) return null;
  const limited = await enforceInspectionReadRate(session, selectedProjectId);
  if (limited) return limited;
  return { projectId: selectedProjectId, operationId: "inspectPushCampaign" };
});
if (grant instanceof Response) return grant;
return invokeCommunication(operation, request, grant, servicesFor(grant.projectId));

The session, membership, and rate-policy functions above are host adapters. Verify them within the current request and match the selected project to the campaign snapshot. Do not cache the executor or grant across requests. The grant uses the same opaque, one-use registry and request/operation/project checks as credential authorization. Mutated requests, clones, replay, and mismatched service projects fail. Session authentication failure returns no read grant. This in-process API does not change external header authentication or hosted-agent permissions. Never expose grants or the session executor through browser props, URLs, headers, or a management wire endpoint. Compose it with the narrow dashboard inspection reader.

Get started

Your agent

React SDK

Email

Installation lifecycle

Push

Server composition

Self-host activation

Runtime invocation and workers

Push admission

Trusted-session inspection reads

​Push admission

​Trusted-session inspection reads

Push admission

Trusted-session inspection reads