ariestools/ariestools-skills

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-w…

Vedi sorgente

Come usare

  1. Copia il comando e controlla il pacchetto prima di installarlo nel tuo ambiente agente.
  2. Controlla strumenti, credenziali e ambienti richiesti nel documento originale.
  3. Descrivi input e risultato desiderato; confronta l’output con le fonti.
npx skills add https://github.com/ariestools/ariestools-skills --skill ariestools-actor

Prima di iniziare

  • L’installazione non include abbonamenti, quote API o accesso ai file.
  • Stelle e installazioni indicano attività, non un test indipendente di qualità o sicurezza.
Documento Skill originale

Contenuto dal repository con titoli, esempi, codice, tabelle, link e immagini preservati.

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(); new throws. name is the branded CreatableName, so cast it ('heartbeat' as CreatableName).
  • Engine-launched actors get no logger, meter or tracer by default, and AccountProviderActor throws without a logger. Supply a locatorContext through the provisioner (logging and telemetry).
  • @ariestools/actor-engine does not re-export the actor classes: import Actor, PeriodicActor and ProviderActor from @ariestools/actor, and NoProviderConnection from @ariestools/provider.
  • A lookup of a moniker the actor or provider did not declare throws ActorEngineDependencyAccessError, and tryGetInstance does not bypass the check.
  • A compiled engine or browser system holds factories and never crosses a realm; only a BrowserSystemManifest does.

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](../ariestools-architecture/SKILL.md) — design and review application authority, independent discovery, worker replacement, effect concurrency, and scoped coordination across actors or hosts.
  • [xy-development](../xy-development/SKILL.md) — 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](../xy-toolchain/SKILL.md) — the xy CLI, Vitest (including Chromium for browser specs), deplint package roles for bin and library packages, and the tslib that decorators such as @creatable() need; this skill builds on it. Install: npx skills add ariestools/ariestools-skills --skill xy-toolchain.
  • [ariestools-sdk](../ariestools-sdk/SKILL.md) — the @ariestools/sdk utilities actors use (creatable, CreatableName, loggers), its zod and 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](../ariestools-sdk-react/SKILL.md) — 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.

dallo stesso repository

Altri Skills

Tutti gli Skills
ariestools
Community

ariestools-sdk

Aries Tools shared TypeScript/JavaScript libraries published from the sdk-js monorepo. Covers the @ariestools/sdk umbrella (assert, delay, fetch, hex, promise, storage, zod helpers, and other modules), specialist packages (express, storage-adapters, threads, testing, telemetry, crypto-auth, eth-address, pixel, json-rpc-engine, sdk-meta), root-barrel import conventions, runtime peers (zod, OpenTelemetry), the Node 26 baseline, and migration from retired @xylabs/ names. Use when importing, install

Installazioni / 1h
2
GitHub Stars
0
Aggiornato
11 nov
ariestools
Community

xy-toolchain

The Aries Tools TypeScript toolchain (@ariestools/toolchain) behind XY, XYO, and XL1 repositories — the stable xy and experimental xyex CLIs, xy.config.ts, and the shared ESLint, TypeScript, and Vitest configs. Use when setting up a repo or choosing a project profile; running or debugging build, lint, test, or xy check; configuring package output; fixing deplint or publint findings; linting AGENTS.md and docs with xy agent; supporting product planning (papers, roadmap, PRDs) with xy repo init an

Installazioni / 1h
2
GitHub Stars
0
Aggiornato
11 nov
ariestools
Community

xy-agent

Repository documentation conventions for AI agents — the AGENTS.md entry point, thin per-tool adapters (CLAUDE.md, GEMINI.md, copilot-instructions), the docs/ lifecycle tree, and papers/ normative baselines. Covers required AGENTS.md sections, the size budget, front matter and document states, decision records, dated evidence documents, supersession and archiving, the generated docs index, and auditing for rot. Use when writing, reorganizing, or auditing AGENTS.md, adapter files, docs/, or paper

Installazioni / 1h
1
GitHub Stars
0
Aggiornato
11 nov
ariestools
Community

xy-development

Core development standards for TypeScript conventions, Git workflow, testing principles, behavior-preserving refactors, repository workflow, and the Definition of Done. Use when writing or reviewing TypeScript or organizing imports; writing tests; refactoring, moving code between packages, or auditing a monorepo's package structure; running a repo's build, lint, test, or dev commands; adding or upgrading dependencies; committing, branching, merging, releasing, or deploying; writing PRD acceptanc

Installazioni / 1h
1
GitHub Stars
0
Aggiornato
11 nov