integration.lssm-os-provider-gcp

GCP hosting transport for LSSM OS

CloudRunClient implements scoped Cloud Run v2 service discovery, creation, inspection, guarded update/deletion and asynchronous operation readback. It uses native fetch and an injected token provider, with no mandatory cloud SDK or Kubernetes component.

Boundary and ownership

This is a server transport for composition behind the existing Runtime Node ProviderLifecyclePortV1. It does not issue execution authority, journal effects, reserve budgets, or introduce another agent/task store. The execution host must load current Connect authority, record the effect intent before mutation, persist returned operation handles and reconcile unknown outcomes before another effect. A returned operation handle means accepted, not deployed or deleted.

The initial transport targets single-container, request-driven services with one CPU and 256/512 MiB memory. Scope fixes the project, region, service account and maximum scaling ceiling. Plans require image digests and a parent plan digest; the host must bind that digest to the authorized plan, since syntax validation is not attestation verification. New services scale to zero with IAM invocation checks enabled. The client does not grant allUsers or change IAM policies; enabling IAM checks alone does not remove preexisting IAM grants on adopted services.

Updates require a current resource UID/etag and an explicitly adopted target. They preserve existing environment/secret references, probes, protocol, warm capacity, request timeout and unrelated network configuration. Changes to service identity, port, GPU/multi-container/always-allocated-CPU topology require a separate reviewed migration. An update never creates a missing service.

Deletion checks UID/etag again and sends an etag precondition. A same-named replacement cannot be silently deleted. The host must verify operation completion and resource absence before marking cleanup complete.

Usage

Import CloudRunClient from @lssm-tech/integration.lssm-os-provider-gcp/cloud-run.

const client = new CloudRunClient({
  scope: {
    projectId: 'example-project',
    region: 'europe-west1',
    serviceAccount: 'example-worker@example-project.iam.gserviceaccount.com',
    maximumInstances: 1,
  },
  accessToken: (signal) => credentialProvider.getAccessToken(signal),
});
const services = await client.listServices();

Provide a trusted token source from the host connection service. Do not pass credentials in plans, observations, browser UI or logs. Calls stay on Google's fixed API origin, refuse redirects, bound token acquisition and response reads, and never automatically retry mutations. CloudRunRequestError.indeterminate distinguishes an uncertain external effect from an admission/authentication failure before dispatch. Caller abort signals bound composed operations.

Discovery fails on unreachable regions, repeated pagination tokens or conflicting resource identities instead of returning a partial inventory. Observations omit container environment values and provider error messages. Readiness requires a successful terminal condition and matching observed generation/revision.

Qualification status

Implementation and local transport regression tests are available. Live Cloud Run qualification requires an active, separately budgeted test environment. No Cloud Run workload, GKE, VM, jobs, full cloud lifecycle or production Runtime Node authority qualification is claimed here.

Run bun test, bun run typecheck, bun run build, and bun run test:pack. The package test installs its actual tarball without network access and imports both public subpaths using Node and Bun. That does not prove npm publication.