feat(commands): add hosted external-app onboarding

[lilienblum]

Summary

• add await CommandsClient.forDeployment({ deploymentId, apiKey }) for hosted senders
• add createCommandReceiver({ deploymentId, apiKey, target }) for external Container/Daemon receivers
• refresh short-lived manager credentials before expiry and exactly once after 401
• centralize command-capability authorization so OSS and hosted managers enforce the same deployment/target policy
• make manager reassignment recoverable and retry transient receiver bootstrap failures
• split receiver configuration/bootstrap from the lease loop to keep the public receiver implementation focused
• document hosted, injected-runtime, and self-hosted usage

The Alien API key is sent only to the hosted bootstrap endpoint; managers receive only a short-lived command capability.

Validation

• GitHub Rust crates: passed
• GitHub TypeScript packages and CLIs: passed
• commands Vitest: 86/86
• commands typecheck, build/declarations, and Biome
• cargo check -p alien-manager
• focused Rust authorization and stale-manager route tests
• changed-file rustfmt and git diff --check

Draft follow-up

• land the companion hosted bootstrap/control-plane change before merging

[greptile-apps]

Greptile Summary

Adds hosted external-app command onboarding.

• Introduces platform bootstrap for short-lived sender and receiver credentials, including refresh-on-expiry and one retry after authentication failure.
• Adds deployment- and target-scoped command capabilities to manager authorization.
• Refactors receiver configuration and bootstrap while retaining injected-runtime support.
• Updates command-package exports, tests, documentation, and generated platform API specifications.

Confidence Score: 5/5

The PR appears safe to merge based on the eligible follow-up findings.

No blocking failure remains.

Important Files Changed

Filename	Overview
packages/commands/src/bootstrap.ts	Adds hosted bootstrap, connection validation, credential refresh, and one-time retry behavior.
packages/commands/src/client.ts	Adds the hosted deployment client factory and routes manager requests through refreshable connections.
packages/commands/src/receiver-config.ts	Centralizes injected and hosted receiver configuration, token loading, and connection providers.
packages/commands/src/receiver.ts	Integrates refreshable receiver connections while preserving lease processing and shutdown behavior.
crates/alien-manager/src/auth/command_capability.rs	Defines shared deployment- and target-scoped authorization decisions for command capabilities.
crates/alien-manager/src/routes/commands.rs	Applies command-capability authorization across dispatch, status, lease, release, and response routes.
crates/alien-manager/src/auth/subject.rs	Adds the serialized commands scope, sender/receiver capability variants, and command-capability role.
crates/alien-manager/src/stores/sqlite/command_registry.rs	Extends canonical command ownership context with target information for receiver authorization.

Sequence Diagram

sequenceDiagram
  participant App as External app
  participant Platform as Hosted Platform API
  participant Manager as Deployment manager
  participant Target as Command target
  App->>Platform: Bootstrap with deployment ID and API key
  Platform-->>App: Manager URL and short-lived capability
  alt Sender
    App->>Manager: Create command
    Manager->>Target: Dispatch or queue command
    App->>Manager: Poll command status
  else Receiver
    App->>Manager: Acquire target-scoped lease
    Manager-->>App: Command envelope
    App->>Manager: Submit response or release lease
  end
  opt Capability expires or manager returns 401
    App->>Platform: Refresh bootstrap
    Platform-->>App: Updated manager URL and capability
  end

Loading

_{Reviews (8): Last reviewed commit: "chore(sdk): sync commands bootstrap API ..." | Re-trigger Greptile}

[lilienblum]

AWS CloudFormation E2E verification

Tested this PR end to end at Alien head 6d5c74fa26ccea153d3d0dd807ba867334ba802d together with Platform PR alienplatform/platform#221 at d2e934aad79ae2ea117a738a8c9373b52d939cd8, pinned Horizon 004ae1ac87e463e4131e02f7d21be62469e71ecc, and pinned Deepstore 8d2ad0d720b5a369b427be9111baf5549ef04d93 in an isolated composed workspace.

Run details:

• Flow: aws-cloudformation-cf-notifier, worker target, slot 47
• AWS target: account 230470760195, region us-east-2
• Result: 1/1 passed in 1059.37s
• Exact Alien CLI SHA-256: 0bab0ff67e4c8d8ab2284997de29d3597057970930bbd94984f3ab12d21a58a4
• CloudFormation stack e2e-47-aws-cloudformatio-0650160a40 reached CREATE_COMPLETE
• DeploymentRegistration reached CREATE_COMPLETE, proving the cf-notifier callback/import path
• Deployment dep_wbonqzt4d9amo9qavozfnp9gj919 reached running
• Public worker endpoint passed
• Hosted command cmd_dm8mqDwo0IlOy2xUjIQajNs1JIDT completed and all success assertions passed
• A v2 release was pushed with the same exact CLI and the in-place upgrade/current-release assertion passed
• Cleanup completed: the stack reached DELETE_COMPLETE; the project, deployment, and command rows were removed; the target-account tag sweep was empty

The local cross-target release build required a Linux arm64 native bindings addon. Building that addon from this exact commit resolved the prerequisite; it was not a runtime or CloudFormation failure.

The run exposed a pre-existing project/artifact lifecycle gap: project deletion does not remove its per-project ECR repository. The exact test repository and image were manually deleted after the run; this is not introduced by this PR and did not affect the functional result.

Fresh simplicity/security review found no material issues. CI is green and the PR is mergeable.

[lilienblum]

Final hosted Commands E2E result

Retested the external hosted Commands API end to end against this exact PR head (6d5c74fa26ccea153d3d0dd807ba867334ba802d) using a compatible live hosted bootstrap service.

Exact package under test

• Ran pnpm pack from packages/commands at this commit and installed the resulting 57,705-byte tarball in an independent fixture.
• Tarball SHA-256: ffe1840974b70a6ec27f4937b9443711c59a91ddcc07dbb6f27ac0cbc6b07a70.
• This deliberately bypassed the published @alienplatform/commands@3.3.11, which does not contain CommandsClient.forDeployment.
• The reusable fixture is committed and pushed at lilienblum/alien-test@a69d144.

Verification completed

• npm run test:ts passed for the fixture repository.
• Verified that the packed module exports both CommandsClient.forDeployment and createCommandReceiver.
• Verified the standalone resize handler result locally.
• Built the standalone deployment with this PR CLI using alien build --platform aws.
• Deployed a command-enabled Daemon target named external-image-processor through the generated CloudFormation package.
• CloudFormation reached CREATE_COMPLETE, then the deployment reached running.
• External receiver used createCommandReceiver({ deploymentId, apiKey, target }) and receiver.command("resize-image", ...).
• External sender used CommandsClient.forDeployment({ deploymentId, apiKey }) and invoked the Daemon-targeted command.
• The receiver leased and submitted the command successfully on attempt 1.
• The sender asserted the exact returned value: { "format": "rgba", "width": 1, "height": 1, "rgbaBase64": "/wAA/w==" }.

Result: pass. This covered the actual hosted bootstrap endpoint, both new convenience APIs, short-lived sender/receiver capabilities, manager polling and leasing, response submission, and sender result polling—not the older direct POST /v1/commands test path.

Final cleanup passed: the CloudFormation stack and per-run cloud resources were deleted, local test services and volumes were stopped, and temporary credentials were removed. A final cloud re-list found no resources for the run.

Manual fixture: https://github.com/lilienblum/alien-test/tree/dan/ALIEN-422-standalone-commands-fixture/standalone-commands