Infra Pulumi Provider

Spec

• Export surface: @sl-testing/ac-pulumi.
• Purpose: own the custom Pulumi provider source, provider schema, generated Node SDK distribution, plugin packaging, and install-time plugin bootstrap.
• Owns: core/infra-pulumi-provider/provider, core/infra-pulumi-provider/postinstall.js, generated SDK artifacts under dist, provider schema/codegen inputs, and release packaging logic for the published Pulumi package.
• Does not own: Terraform env roots, platform API behavior, or product resource semantics beyond faithfully exposing the platform contract.
• Dependencies: resource semantics come from core/api/AGENTS.md and the owning domain module AGENTS.md files.
• Cross-module contract: consumers import provider resources only from the package root @sl-testing/ac-pulumi.
• Provider package contract:
  • this module ships the agentcloud Pulumi resource provider plus the generated Node SDK published as @sl-testing/ac-pulumi
  • provider source-of-truth lives in provider/*.go; checked-in dist output is generated, not hand-edited
  • release packaging runs through core/repo-tools/src/build-ac-pulumi-package.sh, injects main.providerVersion, runs pulumi package gen-sdk, patches the generated Node wrapper, and bundles provider binaries plus postinstall.js
  • published installs auto-attempt pulumi plugin install resource agentcloud <version> --reinstall from the packaged binary, but do not hard-fail npm install if Pulumi or the plugin install step is unavailable
  • bundled plugin binaries currently target darwin-arm64 and linux-x64
• Provider scope and config:
  • the provider manages project-owned resources inside one existing project at a time
  • provider config keys are agentcloud:apiUrl and agentcloud:projectId
  • resource projectId may override provider config per resource; reads prefer explicit projectId, then the compound import ID, then provider config
  • agentcloud:apiUrl may come from Pulumi config or AC_API_URL; projectId must come from Pulumi config or resource input, not an env fallback
  • previews synthesize placeholder canonical IDs with zero suffixes until the API returns the real resource ID
  • project-owned import IDs use <projectId>/<resource_type>/<resource_id>
  • the provider does not use workspace-era identifiers in the product contract
• Provider connectivity and auth:
  • agentcloud infra init persists agentcloud:projectId and agentcloud:environment=prod, but not agentcloud:apiUrl
  • machine-side agentcloud infra plan|apply|drift|destroy uses the canonical remote Pulumi backend for the target stack
  • agentcloud infra apply never implicitly reuses a default saved plan file; saved-plan apply happens only with --plan-file
  • auth resolution order is AC_BOOTSTRAP_TOKEN exchange at POST /v1/runtime-auth/exchange, then AC_TOKEN, then AC_TOKEN_FILE, then AC_SESSION_COOKIE, then AC_SESSION_FILE, then ~/.agentcloud/session.cookie
  • AC_TOKEN_FILE is bearer-token-only and rejects cookie-form values
  • AC_SESSION_FILE is cookie-only and rejects bearer-token-only values
• Provider surface:
• managed resources are Secret, ProjectRole, ProjectRoleRule, ProjectRoleBinding, Database, Image, Machine, AgentConfiguration, Job, Service, ServiceDeploymentResource, and SlackConnection
  • invoke helpers are permissionCatalog, agentRuns, messages, jobRuns, serviceDeployments, imageVersions, imageVersionsByImage, and logs
  • invoke helpers are project-scoped, read-only helpers; lifecycle ownership belongs to resources
• Resource lifecycle contract:
  • Secret: key is immutable; update re-puts the value; reads never fetch plaintext back from the API and preserve the Pulumi-encrypted last-known value in state
  • ProjectRole: name is immutable; update patches description only
  • ProjectRoleRule: wraps role grants; roleId and permission are immutable; updates replace rule scope/resource selectors by deleting the old rule and granting a new one; validated rule selectors are limited to canonical product resource types
  • ProjectRoleBinding: binds subjectType + subjectId + roleId; valid subject types are user, agent_configuration, job, service, and public; create de-duplicates by looking up an existing binding on conflict; updates are delete-and-recreate
  • Database: create/read/delete only; name is immutable; state stays minimal with projectId, name, databaseId, and status; no restore, endpoint metadata, credentials metadata, cluster identifiers, AWS ARNs, or size classes are exposed
  • Image: name and sourceType are immutable; updates patch dockerfilePath, contextPath, and registryRef; registry-source reads preserve explicit registryRef input when needed; delete retries deterministic 409 conflicts briefly before surfacing failure
  • Machine: name is immutable; image version, size, and working directory update in place; reads treat deleted status as absent
  • AgentConfiguration: this is the durable configuration object, not the runtime agent; name and provider are immutable; image version, size, working dir, model, Codex thinking, instructions, and idle timeouts update in place
  • Job: name is immutable; image version, command, input schema, timeout, and max parallel runs update in place
  • Service: type and name are immutable; cpu, memoryMb, port, and healthcheckPath update in place; reads expose live status and serviceUrl
  • ServiceDeploymentResource: models service deploy operations, not the service definition; projectId and serviceId replace, imageVersionId replace, create/update call POST /deploy and wait up to 10 minutes for a healthy deployment, and a matching current healthy deployment is treated as idempotent success; delete is intentionally a no-op and does not rollback
• There is no standalone Pulumi Function resource. Function services expose manifest-backed functions from the deployed image and are managed through the Service plus ServiceDeploymentResource contract.
• Replace, import, and error semantics:
  • default rule is dumb/simple mapping: safe scalar knobs update in place; ownership/identity fields replace
  • canonical project-scoped import IDs exist for all managed resources; most resources can read/delete from the import ID alone, but ProjectRoleRule and ProjectRoleBinding currently still rely on state-carried IDs on follow-up read/delete
  • surfaced provider errors preserve API error_code
  • 400 maps to InvalidArgument
  • 401 and 403 map to PermissionDenied
  • 404 maps to NotFound
  • 409 maps to FailedPrecondition
  • delete treats NotFound as success for managed resources
  • runtime agents are not Pulumi-managed resources
• Provider generality:
  • the provider is product-level and project-agnostic
  • it does not hardcode meta-project names, resource names, service names, or workflow assumptions
  • it does not ship a Project resource and does not manage projects.main_agent_configuration_id or projects.main_agent_id
  • project main-agent pointers remain API-managed or userland-managed

Testing

• Fast proof: npm run -w core/infra-pulumi-provider lint.
• Provider proof: (cd core/infra-pulumi-provider/provider && go test ./...).
• SDK proof: rerun bash core/repo-tools/src/build-ac-pulumi-package.sh --version <version> when schema/codegen, provider packaging, or plugin bootstrap changes.
• Install proof: run bash core/repo-tools/src/smoke-ac-pulumi-npm-install.sh [--version <version>] for the published package path.

Deployment

• Ships as the published Pulumi provider and generated SDK package, not as a long-running runtime.
• Any provider contract change must be regenerated and republished before meta-project stacks consume it.
• Keep package.json, the Pulumi package metadata, and injected provider binary version aligned across release artifacts.

Monitoring

• Watch provider apply/import failures, auth resolution regressions, schema drift, postinstall/plugin install regressions, and generated SDK mismatches against the live API.
• After release, validate at least one representative Pulumi program still previews and applies.

Risks

• Provider drift breaks infrastructure reconciliation and meta-project deployment.
• Import/read drift is especially risky because Pulumi state adoption depends on canonical compound IDs working consistently.
• Never patch generated output without updating the underlying provider/schema pipeline.