ariestools-actor
Aries Tools actor-kit and its host kits: @ariestools/actor, actor-model, actor-engine, provider and provider-model (plus the deprecated actor-system alias), @ariestools/cli-kit (-node, -yargs, -daemon) and @ariestools/browser-kit (-page, -worker, -service-worker, -plugin). Covers Actor, PeriodicActor and ProviderActor lifecycles, provider descriptors, monikers and bindings, compiling, launching and supervising an actor engine, cli-kit process shells and SYS_EXITS exit codes, and browser-kit realms. Use when writing actors or actor-engine providers, hosting them with cli-kit or browser-kit, or migrating from actor-system, @ariestools/actor-cli or the @xyo-network/actor-cli-kit shims.
How do I install this agent skill?
npx skills add https://github.com/ariestools/ariestools-skills --skill ariestools-actorIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill is a comprehensive technical reference for the Aries Tools Actor framework, providing architectural guidance and implementation details for actors, providers, and host environments (CLI and Browser). It focuses on teaching developers how to use the framework correctly and securely, including topics like dependency isolation and credential redaction, with no malicious patterns or security risks detected.
- Socketpass
No alerts
- Snykwarn
Risk: MEDIUM · 1 issue
What does this agent skill do?
Aries Tools Actors
Authority. This skill is maintained only in ariestools/ariestools-skills; edit there, not in installed copies.
Versions. Verified against actor-kit 2.0.0 (@ariestools/actor, actor-model, actor-engine, actor-system, provider, provider-model), @ariestools/cli-kit 2.1.0 and @ariestools/browser-kit 2.0.0, with @ariestools/sdk 9.0.1. The sources are the private ariestools/actor-kit, ariestools/cli-kit and ariestools/browser-kit repositories; their READMEs lag the code (stale upstream docs).
Skill identity. When you present a plan, an acknowledgement, or a completion summary, state which skills informed it as ariestools-actor v<version>, and list each other active skill from this pack the same way. Read the version from this file's metadata.version, never from an example.
Scope. The six actor-kit packages, the four @ariestools/cli-kit* packages and the five @ariestools/browser-kit* packages, plus migration from @ariestools/actor-system, host-kit 1.x, the retired @ariestools/actor-cli and the npm-deprecated @xyo-network/actor-cli-kit* shims. Not covered: @ariestools/sdk utilities and their peers (ariestools-sdk); build, lint, deplint, Vitest and Chromium setup (xy-toolchain); React UI on @ariestools/sdk-react* (ariestools-sdk-react); and XL1 specializations such as chain locator wiring, ChainActor, wallet resolution and @xyo-network/xl1-browser-system (xyo-skills).
@ariestools/cli, the aries operator CLI, is a product built with cli-kit, not a kit, and is out of scope: see what this skill does not cover and aries --help.
Model. One host-agnostic engine, @ariestools/actor-engine, compiles config, resolves one provider graph, constructs actors and supervises them. Domain code depends on @ariestools/actor and @ariestools/actor-engine, never on a host kit. cli-kit adds the Node process boundary and makes supervision sequential; browser-kit adds realm boundaries and keeps the engine's parallel default. Both 2.x host kits still need the deprecated @ariestools/actor-system alias beside them (host kits still on actor-system).
Distributed responsibilities. Before assigning application work across processes or hosts, introducing a controller, or choosing recovery and effect rules, consult ariestools-architecture when available. Local lifecycle supervision remains useful: assess separately who owns business obligations, outcome acceptance, and recoverable progress. Prefer independently discovering, replaceable workers with safe concurrent effects; justify coordinated authority by its invariant or resource constraint. This policy does not alter the kit APIs or reopen an accepted application protocol during routine lifecycle work.
Traps.
- Create actors with
await X.create(params)under@creatable();newthrows.nameis the brandedCreatableName, so cast it ('heartbeat' as CreatableName). - Engine-launched actors get no logger, meter or tracer by default, and
AccountProviderActorthrows without a logger. Supply alocatorContextthrough the provisioner (logging and telemetry). @ariestools/actor-enginedoes not re-export the actor classes: importActor,PeriodicActorandProviderActorfrom@ariestools/actor, andNoProviderConnectionfrom@ariestools/provider.- A lookup of a moniker the actor or provider did not declare throws
ActorEngineDependencyAccessError, andtryGetInstancedoes not bypass the check. - A compiled engine or browser system holds factories and never crosses a realm; only a
BrowserSystemManifestdoes.
Runtime. Treat Node 26 as the floor for the whole family (26.9 for @ariestools/cli-kit-daemon); actor-kit's declared >=18 understates it (runtime floors).
This skill builds on xy-development, xy-toolchain and ariestools-sdk. Load only the reference needed for the task:
References
Overview, packages and install
Read first when choosing which actor-kit, cli-kit or browser-kit packages a package needs or which package exports a name; installing the 2.x family with its peers (@ariestools/sdk, zod, @opentelemetry/api, and yargs for cli-kit-yargs) while keeping one copy of the SDK and of the engine; checking the runtime floors; judging whether an upstream README is stale; or deciding whether a topic belongs to another skill.
Actors
Read when writing an Actor, PeriodicActor, ProviderActor or AccountProviderActor: creating one with await X.create() under @creatable(), overriding startHandler / stopHandler, registering timers, implementing runPass or run and readiness, choosing a trigger (runOnce, runToCompletion, wake or scheduling), handling fatal errors and maxConsecutiveFailures, recording metrics and spans, or booting and stopping actors without an engine (createMemoryLocator, bootActors, stopOrShutdown, the installed-actor catalog).
Providers and resolution
Read when defining a Provider and its moniker; writing a provider descriptor (monikers, connectionTypes such as NoProviderConnection, dependencies) and its engine create / dispose factory; binding monikers to connections or pinned providers in config; declaring optional dependencies; or diagnosing a resolution error (UnboundProviderError, AmbiguousProviderError, …) or an ActorEngineDependencyAccessError from an undeclared lookup.
Actor engine
Read when registering actors in an ActorEngineCatalog; compiling config with compileActorEngine and describing the plan with describeActorEnginePlan; launching with launchActorEngine, launchCompiledActorEngine or, for actors the host built, launchActors; running one-shot actors (runMode: 'one-shot'); choosing parallel or sequential supervision; handling whenTerminal() failures and session stop; tracing boot with startActorEngine and renderActorEngineBoot; writing a custom provisioner; or giving engine-launched actors the logger, meter and tracer they lack by default (logging and telemetry).
CLI hosts (cli-kit)
Read when running an engine in a Node command-line or service process: launchCliSystem and runCliSystemUntilInterrupt, process hosts from @ariestools/cli-kit-node, runProcessApplication and SYS_EXITS exit codes from createSysExitFailureMapper and CliConfigError, yargs command catalogs with @ariestools/cli-kit-yargs, long-running service helpers, local daemons with createDaemonKit from @ariestools/cli-kit-daemon, or shaping a bin package and its launcher.
Browser hosts (browser-kit)
Read when hosting actors in a browser: BrowserActorCatalog, BrowserSystemConfig, compileBrowserSystem and launchCompiledBrowserSystem in the owner realm, assigning actors to realms with host, page lifecycle, dedicated or shared workers over a MessagePort, service workers, extension background and port realms with an authorize callback, typed provider proxies, the realm security boundary, testing realm code, or why only a BrowserSystemManifest, never a compiled system, crosses a realm.
Migration
Read when moving actor-kit 1.3 to 2.0 (enforced dependency access, closing scopes, SDK 9), renaming @ariestools/actor-system imports to @ariestools/actor-engine, upgrading cli-kit or browser-kit from 1.x to 2.x, replacing the retired @ariestools/actor-cli 1.3.0 helpers (runActorsService, runActorOnce, …) or the npm-deprecated @xyo-network/actor-cli-kit* shims, or keeping one engine copy while the host kits pull in actor-system.
Related skills
These are navigation links, not dependencies; each skill installs separately.
- ariestools-architecture — design and review application authority, independent discovery, worker replacement, effect concurrency, and scoped coordination across actors or hosts.
- xy-development — TypeScript, Git, testing principles and the Definition of Done; this skill builds on it. Install:
npx skills add ariestools/ariestools-skills --skill xy-development. - xy-toolchain — the
xyCLI, Vitest (including Chromium for browser specs), deplint package roles for bin and library packages, and thetslibthat decorators such as@creatable()need; this skill builds on it. Install:npx skills add ariestools/ariestools-skills --skill xy-toolchain. - ariestools-sdk — the
@ariestools/sdkutilities actors use (creatable,CreatableName, loggers), itszodand OpenTelemetry peers, and the root-barrel import rule; this skill builds on it. Install:npx skills add ariestools/ariestools-skills --skill ariestools-sdk. - ariestools-sdk-react — React UI on
@ariestools/sdk-react*, for apps whose pages also host browser-kit realms. Install:npx skills add ariestools/ariestools-skills --skill ariestools-sdk-react. - XL1 browser and CLI specializations live in the separate xyo-skills pack.
Install this skill with npx skills add ariestools/ariestools-skills --skill ariestools-actor, or in an xy repository with pnpm xy skills pick --skill ariestools-actor, which also records it as required. Since toolchain 10.1.4 it is in the toolchain's skills catalog: xy skills lint requires it, together with ariestools-sdk, wherever a workspace package produces or depends on an actor-kit, cli-kit or browser-kit package, and version-checks it. Through 10.1.3 it is outside the catalog, so xy skills pick and the commands.skillsLint keys reject it; install it there with pnpm xy skills add ariestools/ariestools-skills --skill ariestools-actor -y. See skills and work tracking for the other routes and their caveats.
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/ariestools/ariestools-skills/ariestools-actor">View ariestools-actor on skillZs</a>