[AAASM-1228] ✨ (runtime): Add SDK runtime auto-detection and lifecycle (F115)#41
Merged
Merged
Conversation
Module-level constants and the install-hint message shared by the four
lifecycle functions in subsequent commits. RUNTIME_SUBPACKAGE follows
the esbuild npm-optionalDependencies pattern
(`runtime-{platform}-{arch}`).
Not re-exported from src/index.ts to avoid colliding with the existing
gateway-based @agent-assembly/sdk initAssembly.
Refs AAASM-1228 / AAASM-1205.
Resolves the aasm binary in this order: $PATH → ~/.local/bin/aasm →
node_modules/@agent-assembly/runtime-{platform}-{arch}/bin/aasm
(esbuild-style optionalDependency) → /usr/local/bin/aasm (Docker base
image). The bundled-runtime path is computed relative to import.meta.url
so it resolves whether this module is executed from src/ (tests) or
dist/esm/ (built).
Refs AAASM-1228.
Promises true iff a connect to 127.0.0.1:DEFAULT_PORT lands within 100 ms. Settles on the first of connect / timeout / error and tears down the socket — the lifecycle orchestrator uses this to skip startRuntime() when the sidecar is already up (idempotent re-init). Refs AAASM-1228.
Spawns `aasm serve --port <port>` with stdin closed, stdout+stderr appended to .aasm-runtime.log under logDir (default: process.cwd()), detached: true + child.unref() so the Node event loop can exit independently of the sidecar. Returns the ChildProcess handle; the caller does not await. Refs AAASM-1228.
Implements the F115 four-step lifecycle: probe → resolve binary → spawn. Returns early when isRunning() reports a live sidecar (idempotent re-init), throws Error(INSTALL_HINT) when findAasmBinary() returns null. agentId is accepted per the AAASM-1228 signature but is not consumed at the lifecycle layer; the existing gateway-aware @agent-assembly/sdk initAssembly handles register-and-connect once the sidecar is reachable. Closes AAASM-1228.
19 tasks
src/runtime.ts shipped using `dirname(fileURLToPath(import.meta.url))`
to anchor the bundled-runtime sub-package path resolution relative to
this module. That breaks `tsc -p tsconfig.cjs.json` with TS1343
(import.meta only allowed when --module is es2020+/nodenext) and
cascades into the entire `pnpm run build` → packaging-test → test
matrix going red on every Node version × OS combination.
Switch to the project-wide `createRequire(${cwd()}/package.json)`
pattern used by src/native/client.ts, src/core/init-assembly.ts, and
the framework-detection modules. It works in both ESM and CJS contexts
and resolves the optional dep via Node's standard module algorithm,
which is also more correct than the hand-rolled relative-path walking.
Refs AAASM-1228.
Codecov Report❌ Patch coverage is
📢 Thoughts on this report? Let us know! |
Module preamble, imports, and two fixture helpers used by the four
F115 scenario tests landing in subsequent commits:
* makeFakeAasm(dir) — writes an executable aasm shim into dir.
* makeBundledRuntimePackage(root) — materialises a fake
node_modules/@agent-assembly/runtime-{platform}-{arch}/{package.json,
bin/aasm} tree under root so the createRequire-based bundled-path
resolver in src/runtime.ts has something real to resolve.
Refs AAASM-1228 / AAASM-1230.
Creates an executable aasm shim in a tmp dir, sets process.env.PATH to that dir (and HOME to a non-existent path to disable the ~/.local/bin fallback), then asserts findAasmBinary returns the exact tmp-dir path. Covers the primary brew install / cargo install / curl installer code path. Refs AAASM-1228 / AAASM-1230.
Materialises a fake node_modules/@agent-assembly/runtime-{platform}-{arch}
sub-package under a tmp cwd, points PATH/HOME at non-existent dirs to
suppress the earlier search-path branches, and asserts findAasmBinary
returns the bundled bin/aasm path. Exercises the createRequire-based
resolution that replaced the import.meta.url approach in commit
8eecb52.
Refs AAASM-1228 / AAASM-1230.
createRequire.resolve returns the realpath form of the optional sub-package's package.json. On macOS that means /var/folders/... → /private/var/folders/... after symlink resolution, so the prior direct fake-path comparison fails. Apply realpathSync to the expected path so the assertion holds on Darwin as well as Linux. Refs AAASM-1228 / AAASM-1230.
Empties every search location (PATH, HOME, cwd without node_modules) and asserts initAssembly rejects with an Error whose message is exactly INSTALL_HINT — i.e. the full pnpm / brew / curl install copy-paste the runtime ships to end users. Refs AAASM-1228 / AAASM-1230.
Binds an ephemeral 127.0.0.1 port (avoids racing with whatever might be on DEFAULT_PORT 7878 on the dev box), points PATH/HOME at empty locations to guarantee findAasmBinary would fail, then calls initAssembly(undefined, port). The orchestrator must short-circuit on isRunning() and resolve cleanly without spawning a second sidecar — the structural guarantee that repeated init_assembly invocations are idempotent. Closes the 4th AAASM-1230 AC scenario for the Node.js SDK. Refs AAASM-1228 / AAASM-1230.
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Target
Task summary:
Add
src/runtime.ts— a new submodule that implements the F115 runtime lifecycle for the Node.js SDK: locate theaasmRust sidecar, probe whether it's already running, start it if not, and report a clear install hint when no binary is found. The new orchestrator is exposed asinitAssembly(agentId?)from@agent-assembly/sdk/runtimeand is not re-exported fromsrc/index.ts— the existing gateway-basedinitAssembly(config)keeps its meaning.Task tickets:
Key point change (optional):
Binary search order:
$PATH(delimiter-split)brew install,cargo install~/.local/bin/aasmcurl | shnode_modules/@agent-assembly/runtime-{platform}-{arch}/bin/aasmpnpm add agent-assembly(optionalDependency)/usr/local/bin/aasmEffecting Scope
Tests for
runtime.tsare intentionally deferred to AAASM-1230 (cross-SDK test sub-task) per the story decomposition. Local verification:pnpm typecheck→ cleanpnpm lint→ cleanpnpm test→ 126/131 pass; the 3 failures (tests/packaging/*) are pre-existing onmaster(need native NAPI build artifacts not available in this environment).Description
5 granular commits, each adds one logical unit:
✨ (runtime): Add src/runtime.ts skeleton with F115 constants✨ (runtime): Add findAasmBinary() resolver across the 4 install paths✨ (runtime): Add isRunning() local TCP liveness probe✨ (runtime): Add startRuntime() detached sidecar spawn✨ (runtime): Add initAssembly() lifecycle orchestrator