Alaskan bot reference

An Alaskan bot is an npm package with a CLI, a SKILL.md and a manifest: the alaskan field in its package.json. How to make one is in Build an Alaskan bot.

The manifest

alaskan  { name, job, tagline, about, breed?, coat?, skill, setup?: [line],
           commands: [Command], secrets?: [Secret], network?: [host],
           pricing?: {model, note?} }
Command  { id, title, run, inputs?: [Input], writes?, kind? }
Input    { id, label, default? }
Secret   { id, label, url }

Field	What it is	Rules and default
name	The bot's name, as the team page and the marketplace show it.	Required, at most 40 characters.
job	A few words, like the dogs' jobs.	Required, at most 40.
tagline	One line on what it does.	Required, at most 140.
about	A few sentences more.	Required, at most 600.
breed	The dog it appears as: kleekai, husky or malamute.	Default husky.
coat	aurora, ember, glacier or twilight.	Default aurora. Malamutes have one coat, so theirs is ignored.
skill	The path to the skill file inside the package, ending .md.	Required. It must be in the published package (in files, if the package has files).
setup	Command lines run once in each fresh machine after install.	Optional, at most 3; default none. Each starts with the package's own bin and takes no placeholders.
commands	What a dog can run, below.	1 to 12.
secrets	Environment variables the CLI needs, below.	0 to 5; default none.
network	The hosts the CLI talks to, shown to the company before it adds the bot: api.example.com or *.example.com, with no scheme or path.	At most 20; default none.
pricing	How it's paid for, below.	Default {"model": "free"}.

• A required value that still starts with TODO (what alaskan-labs init leaves) is refused.
• No other fields. The whole alaskan field is at most 16 KB, and the skill at most 32 KB.
• Who made it: the marketplace's creator name is the package's author (its name), else the bot's name.
• The slug: a bot's address is its package name, lower-cased, with anything else as dashes (@acme/report-kit → acme-report-kit).

npx alaskan-labs check, or POST /v1/creators/check, applies the same rules the server does: the CLI carries the server's own copy of them.

Commands

Field	What it is
id	Lower-case letters, digits and dashes, starting with a letter. Workflows and the API name the command by it.
title	What people see, at most 60 characters: "Conversion report". A company's rules for the bot are written in its commands' titles.
run	A command line that starts with one of the package's own bins, with {{input}} placeholders.
inputs	At most 8, each with an id (the placeholder's name), a label, and an optional default. Each must be used in run. One without a default has to be given.
writes	true for a command that changes something outside the machine.
kind	The Decide kind for its card: update, send, book, spend, publish or other. Default update, and only a command that writes has one.

run is plain words (letters, digits and _ . / : = @ % + , -) and placeholders. Nothing a shell reads as syntax is accepted: no quotes, $, ;, |, &, >, backticks, ~, * and the like.

Every input value is passed as one single-quoted argument, never as shell syntax: at most 2,000 characters, on one line. A value that is a whole argument can't start with - (it would read as an option), so write --flag={{input}} to take one that might.

A command that writes is Ask first by default: the dog proposes it as a Decide card showing the command line, its inputs and the hosts it will reach, and it runs once it's approved and the 10-second undo has passed. Read-only commands are Just do. The company moves them like any of the dog's rules: a write moved to Just do is decided by the rule at once (on the Ledger) and runs after the same 10 seconds; a read moved to Ask first waits for a yes; Never refuses either, on the record. An answer typed in words, with no option chosen, doesn't run anything.

Secrets

Field	What it is
id	The environment variable's name: ACME_CONVERT_TOKEN. Names that would change how the machine, the shell or npm behave (PATH, HOME, NODE_OPTIONS, LD_PRELOAD, proxy settings, NPM_CONFIG_*, ALASKAN_* and the like) are reserved.
label	What the company is asked for: "Acme Convert API token".
url	Where to get it, an https link.

The company enters every one when it adds the bot. They're that bot's machine's environment variables for each run, never part of a command line; stored sealed on the server, entered once, never logged, never returned by the API, and deleted when the bot is removed. Wherever a value shows up in a command line or the output, it's masked.

Pricing

pricing.model is one of:

• free (the default): anyone can add it.
• own-account: the company uses its own account with your service (the secret is its own token), and you charge it directly. Alaskan takes nothing.

pricing.note is a short line in your words about how it's paid for, at most 200 characters. subscription and usage are reserved for when Alaskan bills for creators, and refused until then.

Publishing and review

• npx alaskan-labs publish sends the package name, the exact version, bin, author, the manifest and the skill's text.
• The server reads that exact version from the npm registry. npm's copy of the alaskan field is the manifest of record: if the one the CLI sent differs, the publish is refused (409), so what's reviewed is what runs. It records the version's integrity hash and tarball, and keeps the skill text for the moderator.
• A version not on npm yet is a 400; a version already published to Alaskan is a 409. A bot belongs to the account that first published its package; anyone else gets a 409. Publishing is limited to 30 versions a day per account and 20 from one network.
• A bot's first version always waits for a moderator, who approves it or rejects it with a reason the creator sees.
• A new version goes back to review when it changes the setup, commands, secrets, network list or pricing, any part of them: a command's title, line, inputs or writes; a secret's label or link. Until it's approved, companies keep the last approved version. Name, job, tagline, about, breed, coat and the skill change without review.
• A moderator checks that the npm version matches the manifest; that the skill and the descriptions say what the commands do; that every command that changes something outside the machine is marked writes; that the network list is plausible; and that secrets are labelled with where to get them. Rejecting a version takes companies back to the previous approved one. Companies always run an approved version.

Each run

• A machine of its own, made for the run with no snapshots and none of the account's secrets, never the company's main computer.
• npm install -g <name>@<version> at the exact approved version, then setup, then the command, then the machine is stopped, whatever happened.
• Only that bot's secrets, as the machine's environment variables.
• What runs is the version on the Decide card while it's still approved, or a newer approved version whose command is word for word the same; otherwise it isn't run, and the decision's trail says why.
• 10 minutes at most, from install to the command's end. At most 2 runs at once in a workspace; past that, a run is told to try again (429), and an approved write waits its turn.
• A session step with the command line (secrets masked), the package version, the exit code, how long it took and the output: JSON when the CLI gives it, capped at 64 KB (8 KB of its error output when it fails). A write that ran is on the Ledger with who approved it, and its decision's trail gets ran (or not_run, with why).

Removing a bot

Remove deletes the bot's secrets and retires its commands still waiting in Decide: they expire, on the record. The bot's record stays.

In a workflow

A workflow runs a bot's command with a step of its own:

{ "type": "bot", "bot": "<slug>", "command": "<id>", "input": { "days": "7" } }

In a workflow, a command that writes runs only after a decide step in the same run was approved.

The API

The same API as the rest of Alaskan (see API reference): JSON bodies, and errors as {error} with a 4xx status; publish adds errors: [string] for a manifest's problems. The CLI sends Authorization: Bearer <creator token> (tokens start alc_). A creator token works only on /v1/creators/publish and /v1/creators/bots; making and revoking tokens, and moderation, are done signed in on the web.

For creators

• POST /v1/creators/token {label?} (signed in on the web with an email account) → {token, id, label, createdAt}, the token shown once. Up to 5 per account.
• POST /v1/creators/tokens → {tokens: [{id, label, createdAt, lastUsedAt}]}.
• POST /v1/creators/token/revoke {id} → {ok}.
• POST /v1/creators/check {package: {name, version, bin}, manifest} → {ok, errors, manifest?, slug?}. No token needed.
• POST /v1/creators/publish {package, version, bin, author, manifest, skill} (creator token) → {bot: {id, slug, name, package}, version, status: "in_review" | "approved", first?, changed?}.
• GET /v1/creators/bots (creator token, or the web) → {bots: [{id, slug, package, name, live, installs, createdAt, versions: [{version, status, createdAt, reviewedAt, reason, changed, integrity, tarball}]}]}, newest version first.

The marketplace

• GET /v1/marketplace/bots (public, no sign-in) → {bots: [Bot]}: the approved bots, at the newest approved version of each, most installed first.
• GET /v1/marketplace/bots/<slug> → {bot: Bot}; 404 for one that isn't approved.

Bot { slug, name, job, tagline, about, breed, coat, creator: {name},
      commands: [{id, title, writes, kind, inputs: [{id, label, default?}]}],
      secrets: [{id, label, url}], network: [host], pricing: {model, note},
      package: {name, version}, installs, updatedAt }

In a workspace

• POST /v1/workspace/bots/install {slug, secrets: {ID: value}} → {dog}: the bot joins the team, with every secret given. Up to the team's 12 dogs, and each bot once.
• POST /v1/workspace/bots/secrets {dogId, secrets} → {dog}, replacing the ones given.
• POST /v1/workspace/bots/remove {dogId} → {ok, removed: {id, name}}.
• POST /v1/workspace/bots/run {dogId, command, input: {id: value}} → {session} for a read under Just do, or {decision} otherwise: pending, decided by a Just-do rule (auto, runs after the undo window) or refused by a Never rule (declined). 429 when both of the workspace's machines are busy.

A bot dog carries bot: {slug, package, version, creator: {name}, network, writes, commands, secrets: [{id, label, url, set}], pricing, available}; a run's Session carries bot: {slug, package, version, command, commandLine, exitCode, durationMs, simulated, output?, json?, outputTruncated?, stderr?, decisionId?}; a bot command's Decision carries bot: {slug, package, version, command, title, commandLine, inputs: [{id, label, value}], network, writes}.

Moderation

• GET /v1/creators/review or POST /v1/creators/queue → the versions waiting, each with its manifest, skill, what changed and the previous approved version (moderators only).
• POST /v1/creators/review {botId, version, approve, reason} → {bot, version, status}. A reason is needed to reject.