{"_id":"@storybloq/agkit","_rev":"2-c8a3c44c7b0b9735105ab9fc2bab656e","name":"@storybloq/agkit","dist-tags":{"latest":"0.1.0"},"versions":{"0.0.1":{"name":"@storybloq/agkit","version":"0.0.1","license":"MIT","_id":"@storybloq/agkit@0.0.1","maintainers":[{"name":"ashayegh","email":"shayegh@me.com"}],"homepage":"https://github.com/Storybloq/agkit#readme","bugs":{"url":"https://github.com/Storybloq/agkit/issues"},"bin":{"agkit":"dist/cli.js"},"dist":{"shasum":"96093f59ba12bc6b23f3ca18aa4e0c0a47aa1ea6","tarball":"https://registry.npmjs.org/@storybloq/agkit/-/agkit-0.0.1.tgz","fileCount":29,"integrity":"sha512-ggznZEfPsgUNdCWX5xzVGuRE63cPJBpQHNbQSbUyDoBvil+9USi8FYU311OInUjeulWcLHZew3DVFF193Rgasg==","signatures":[{"sig":"MEQCIDUo/smrQR+kGj+eTzynKwF2+qT6d94zZxsvKVvMn52WAiBY4Lt9s92t8fRVMVc1NuHyS8N/HpHIc5cz8AlkF4ADsw==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@storybloq%2fagkit@0.0.1","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":2562149},"type":"module","_from":"file:/home/runner/work/_temp/release/storybloq-agkit-0.0.1.tgz","types":"./dist/index.d.ts","engines":{"node":">=22"},"exports":{".":{"types":"./dist/index.d.ts","default":"./dist/index.js"},"./mcp":{"types":"./dist/mcp.d.ts","default":"./dist/mcp.js"}},"mcpName":"cloud.agkit/agkit","scripts":{"dev":"tsup --watch","test":"vitest run","build":"tsup && node scripts/inline-shared-dts.mjs","scan:dist":"node --import ./scripts/register-ts-resolve.mjs --experimental-strip-types scripts/scan-dist-vocab.mjs","typecheck":"tsc --noEmit","regen:goldens":"tsx scripts/regen-goldens.ts","prepublishOnly":"node scripts/prepublish-guard.mjs && pnpm build && pnpm test"},"_npmUser":{"name":"ashayegh","email":"shayegh@me.com"},"_resolved":"/home/runner/work/_temp/release/storybloq-agkit-0.0.1.tgz","_integrity":"sha512-ggznZEfPsgUNdCWX5xzVGuRE63cPJBpQHNbQSbUyDoBvil+9USi8FYU311OInUjeulWcLHZew3DVFF193Rgasg==","repository":{"url":"git+https://github.com/Storybloq/agkit.git","type":"git"},"_npmVersion":"11.16.0","description":"AgentKit management-plane CLI + MCP server (agkit).","directories":{},"sideEffects":false,"_nodeVersion":"24.18.0","dependencies":{"zod":"^4.4.3","yargs":"^17.7.3","@napi-rs/keyring":"^1.3.0","@modelcontextprotocol/sdk":"1.30.0"},"publishConfig":{"access":"public","provenance":true},"_hasShrinkwrap":false,"devDependencies":{"ajv":"^8.20.0","tsx":"^4.22.4","tsup":"^8.5.1","jq-wasm":"3.0.0-jq-1.8.2","smol-toml":"^1.4.2","typescript":"^6.0.3","@types/node":"^24.13.2","@types/yargs":"^17.0.35","mdast-util-gfm":"^3.1.0","@agentkit-cloud/shared":"workspace:*","micromark-extension-gfm":"^3.0.0","mdast-util-from-markdown":"^2.0.3","@agentkit-cloud/management-core":"workspace:*"},"_npmOperationalInternal":{"tmp":"tmp/agkit_0.0.1_1785565917042_0.7681634579614081","host":"s3://npm-registry-packages-npm-production"}},"0.1.0":{"name":"@storybloq/agkit","version":"0.1.0","description":"AgentKit management-plane CLI + MCP server (agkit).","mcpName":"cloud.agkit/agkit","license":"MIT","repository":{"type":"git","url":"git+https://github.com/Storybloq/agkit.git"},"type":"module","sideEffects":false,"bin":{"agkit":"dist/cli.js"},"engines":{"node":">=22"},"types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","default":"./dist/index.js"},"./mcp":{"types":"./dist/mcp.d.ts","default":"./dist/mcp.js"}},"scripts":{"build":"tsup && node scripts/inline-shared-dts.mjs","dev":"tsup --watch","typecheck":"tsc --noEmit","test":"vitest run","scan:dist":"node --import ./scripts/register-ts-resolve.mjs --experimental-strip-types scripts/scan-dist-vocab.mjs","regen:goldens":"tsx scripts/regen-goldens.ts","prepublishOnly":"node scripts/prepublish-guard.mjs && pnpm build && pnpm test"},"dependencies":{"@modelcontextprotocol/core":"2.0.0","@modelcontextprotocol/server":"2.0.0","@napi-rs/keyring":"^1.3.0","yargs":"^17.7.3","zod":"^4.4.3"},"devDependencies":{"@agentkit-cloud/management-core":"workspace:*","@agentkit-cloud/shared":"workspace:*","@modelcontextprotocol/sdk":"1.30.0","@types/node":"^24.13.2","@types/yargs":"^17.0.35","ajv":"^8.20.0","jq-wasm":"3.0.0-jq-1.8.2","mdast-util-from-markdown":"^2.0.3","mdast-util-gfm":"^3.1.0","micromark-extension-gfm":"^3.0.0","smol-toml":"^1.4.2","tsup":"^8.5.1","tsx":"^4.22.4","typescript":"^6.0.3"},"publishConfig":{"access":"public","provenance":true},"_id":"@storybloq/agkit@0.1.0","bugs":{"url":"https://github.com/Storybloq/agkit/issues"},"homepage":"https://github.com/Storybloq/agkit#readme","_integrity":"sha512-B9F6N+FJ1pxmKBU1c9aeDUSGgHWoR/RsyJRWk6nI6VlYQcY7rjVTtgcR20haMUsoQTMfSR5rEoY1hM8k0HRWVQ==","_resolved":"/home/runner/work/_temp/release/storybloq-agkit-0.1.0.tgz","_from":"file:/home/runner/work/_temp/release/storybloq-agkit-0.1.0.tgz","_nodeVersion":"24.18.0","_npmVersion":"11.16.0","dist":{"integrity":"sha512-B9F6N+FJ1pxmKBU1c9aeDUSGgHWoR/RsyJRWk6nI6VlYQcY7rjVTtgcR20haMUsoQTMfSR5rEoY1hM8k0HRWVQ==","shasum":"d49a82c28ffd391f79a595f090c9483f126f5d49","tarball":"https://registry.npmjs.org/@storybloq/agkit/-/agkit-0.1.0.tgz","fileCount":28,"unpackedSize":2567036,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@storybloq%2fagkit@0.1.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIHb8ZeJF2uUzQVHVP44CUuWAm/LHZQgzz5p/dghDl9DzAiBd7p5pA8BAXJNaMv4BfH1jOyxJ0xTyr9ZxHuJFwPuH8Q=="}]},"_npmUser":{"name":"ashayegh","email":"shayegh@me.com"},"directories":{},"maintainers":[{"name":"ashayegh","email":"shayegh@me.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/agkit_0.1.0_1785582079325_0.6315044158898322"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-01T06:31:56.799Z","modified":"2026-08-01T11:01:19.914Z","0.0.1":"2026-08-01T06:31:57.235Z","0.1.0":"2026-08-01T11:01:19.508Z"},"bugs":{"url":"https://github.com/Storybloq/agkit/issues"},"license":"MIT","homepage":"https://github.com/Storybloq/agkit#readme","repository":{"type":"git","url":"git+https://github.com/Storybloq/agkit.git"},"description":"AgentKit management-plane CLI + MCP server (agkit).","maintainers":[{"name":"ashayegh","email":"shayegh@me.com"}],"readme":"# `@storybloq/agkit` — AgentKit management CLI + MCP\n\n`agkit` is the first-party command-line interface and MCP server for the AgentKit\nmanagement plane. One binary, three surfaces that share a single bundled core: the\n`agkit` CLI, an MCP server (`agkit mcp serve`), and a typed library.\n\nBecause the three surfaces are generated from one command registry, they cannot drift\napart: the same paths, the same flags, the same required scopes, the same plan/apply\nconfirmation ceremony, whether a human types it, an agent calls it as an MCP tool, or\nyour own code imports it.\n\n## Install\n\n```sh\nnpm install -g @storybloq/agkit\n```\n\nRequires Node 22 or newer.\n\nFirst-touch bootstrap without a global install:\n\n```sh\nnpx @storybloq/agkit init\n```\n\n`npx` is supported for first-touch only (OD-24); the primary, supported path is the\nglobal install.\n\n## 60-second quickstart\n\nInstall → log in → set up a project → bind a tier to a model. The last step is a\nproduction rebinding, so it goes through a plan and a typed confirmation.\n\n**1. Install.**\n\n```sh\nnpm install -g @storybloq/agkit\n```\n\n**2. Log in.**\n\n```sh\nagkit login\n```\n\nThe credential lands in your OS keychain. Confirm it took:\n\n```sh\nagkit whoami\n```\n\n**3. Set up the project end to end.**\n\n```sh\nagkit init\n```\n\n`init` asks for what it needs (a project, a label for the publishable key, optionally a\nprovider to store an API key for), prints the whole plan of action before it does any of\nit, and then runs it: it creates the project, mints a publishable key, stores the\nprovider credential you named, seeds recommended default routes, and writes the SDK\nconfig artifact into the repository. Two of those legs are server-authored plans you see\nand approve as they come up.\n\nIt also drops `.agentkit/project.json` in the repo, which pins the active project. That\nis why nothing below needs a `--project` flag.\n\nNon-interactively — CI, an agent, a script — there is no channel to ask on, so `--yes` is\nrequired, and it has to carry the answers it can no longer prompt for: a project selector\n(`--project <id>` for an existing one, `--project-name <name>` for a new one) and a key\nlabel.\n\n```sh\nagkit init --yes --project-name <name> --key-name <label>\n```\n\nBe exact about what `--yes` buys, because the difference is your traffic. It answers the\nplain `y/N` prompts, and it never satisfies a typed confirm. `init`'s second leg — the\nprovider credential plus the default model routes — is prod-rebinding, so under `--yes`\nthat plan is **created and left OPEN, never applied**: the run reports the credential and\nthe routes as `pending`, prints the plan id with a runnable `agkit plan show <plan-id>`\nand `agkit plan apply <plan-id>` pair, and exits **3** — a partial, not a success. The\nproject, the publishable key and the config artifact are real; **your routes are not bound\nuntil you apply that plan** with its typed confirm string, exactly the way step 5 does it.\n\n**4. Bind a tier to a model — as a plan, not an edit.**\n\n```sh\nagkit route create --tier premium --model claude-opus-4-1 --provider anthropic --execution-target cloud_relay --attestation off --plan-only\n```\n\nCreating a model route is **PR** — prod-rebinding. It re-points live traffic, so the\nserver authors a plan instead of mutating anything. `--plan-only` stops right there and\nemits that plan as data (exit 0); nothing has been applied yet. The plan carries its own\nid and, because it is PR-class, the exact confirm string you have to repeat back.\n\n**5. Apply it.** Take the id and the confirm string from the plan step 4 just emitted:\n\n```sh\nagkit apply plan_UKiJIG6eQXCCi-K6cyYxsA --confirm \"apply PR plan: model_route.create\"\n```\n\nBefore it applies anything, the ceremony renders the plan on stderr so you are\nconfirming what the server actually intends to do, not what you meant to ask for:\n\n```text\nPlan plan_UKiJIG6eQXCCi-K6cyYxsA - danger PR (prod-rebinding)\n  expires in 15m 0s\n  !! PROD-REBINDING: this plan re-binds LIVE traffic - model_route.create\n  changes:\n    create model_route /v1/management/projects/00000000-0000-4000-b000-00000000900d/model-routes\n      (absent) -> {\"tier\":\"premium\",\"model\":\"claude-opus-4-1\",\"provider\":\"anthropic\",\"execution_target\":\"cloud_relay\",\"fallback_execution_target\":null,\"attestation\":\"off\",\"enabled\":true,\"default\":false}\n  to proceed, type this confirm string exactly:\n    apply PR plan: model_route.create\n```\n\nOn a terminal you can leave `--confirm` off and type the string when prompted. Plans\nexpire, so a stale one is refused rather than silently re-created. `--yes` is not a\nsubstitute here: destructive and prod-rebinding plans always require the typed string.\n\nSafer classes are cheaper. A read costs no ceremony at all, and an ordinary mutation\ntakes a plain `y/N` that `--yes` answers — the typed confirm string appears only for the\ntwo classes that can break a live app.\n\n## The full command reference\n\nThe catalog is generated from the shipped registry, so it is never hand-maintained and\nnever stale:\n\n```sh\nagkit reference\nagkit reference --json\n```\n\n`agkit reference` prints the human Markdown catalog. `agkit reference --json` prints the\nmachine registry — every command's path, flags, required scopes, danger class, and output\nschema id — which is what you want when you are scripting against the CLI or checking a\nflag spelling.\n\nThe same catalog ships inside this package as `skill/reference.md`, byte-identical to\nwhat the command prints, so an agent can read it without executing anything. The source\nrepository is private, so there is no public docs URL to follow: the command is the link.\n\n## Authentication\n\n### Two login shapes, chosen for you\n\n```sh\nagkit login\n```\n\nWhen a browser is reachable, this runs the OAuth **authorization-code flow with PKCE**\nagainst a loopback redirect on your own machine — nothing but the browser ever sees the\nauthorization code. On an SSH session, in a container, or anywhere a browser cannot be\nopened, it runs the OAuth **device flow** instead: the CLI prints a URL and a user code\nyou enter from any other device. Force that path explicitly with:\n\n```sh\nagkit login --device\n```\n\nWhich flow was chosen is announced on stderr before anything starts, so a headless\nmachine never silently does something other than what you expected.\n\n### Tokens for CI and agents\n\nHumans log in; robots get a minted, scoped, expiring token:\n\n```sh\nagkit token create --name ci-bot --scope routes:read --expires-in 30d\n```\n\nBoth flags are structural, not decoration. `--scope` (repeat it once per scope) makes\nleast privilege the only way to mint — a token cannot be born with more authority than\nyou named. `--expires-in` is required in a non-interactive shell and capped, and there is\nno opt-out flag: every minted token has an end date.\n\nThe secret is displayed exactly once, at mint time, and is never retrievable again. Hand\nit to the consumer through the environment:\n\n```sh\nexport AGKIT_TOKEN=REDACTED_SHOWN_ONCE\n```\n\n### Scopes\n\nA scope names a resource family and a verb, and the verbs form a ladder:\n`read` < `write` < `destroy`. Holding a higher verb satisfies the lower ones **within the\nsame family**, and never across families — a deploy token with write on routes still\ncannot delete an issuer.\n\nThose `family:verb` strings are the whole vocabulary `--scopes` (on login) and `--scope`\n(on a token mint) accept. Both are validated locally against the contract registry before\nanything is sent, so a scope the contract cannot name is a usage error on your machine,\nnever a request the server has to judge.\n\nThree named profiles group that ladder on the **consent screen**. They are labels the\nauthorization server renders for a grant; they are not values `--scopes` accepts.\n\n- **`read-only`** — every read verb, nothing else.\n- **`default`** — every read verb plus write on the configuration families. This is what\n  `agkit login` requests when you pass no `--scopes`, and it is sized to cover\n  `agkit init` end to end. It deliberately excludes destroy, billing, token minting, and\n  the kill switch. The mechanism is subtraction, not a spelling: with no `--scopes` the\n  CLI omits the scope parameter entirely, so consent applies its own default.\n- **`full`** — everything mintable.\n\nThe scope registry itself is not duplicated here, because a hand-copied catalog is a\ncatalog that rots. Every command's required scopes are carried in the generated\nreference — the `scopes` field of each entry in `agkit reference --json`.\n\n### Where credentials come from\n\nOne chain, used identically by the CLI and by the local MCP server, in this order:\n\n1. **`AGKIT_TOKEN`** — when set and non-empty it short-circuits the entire chain; no\n   keychain access is attempted at all. This is the CI and agent path.\n2. **OS keychain**, via `@napi-rs/keyring` — service `agkit-cli`, account = the active\n   profile.\n3. **Credential helper** — a configured executable whose stdout is one bare token.\n4. **A loud, structured failure (exit 2).** There is no silent fallback to a plaintext\n   file and no anonymous request: if no credential is available, the command stops and\n   tells you which remedy applies.\n\nOn SSH and headless boxes the OS keychain is often missing or locked, and step 4 is what\nyou will hit. Two honest ways through it: run `agkit login --device` on that machine, or\nmint a token elsewhere and export `AGKIT_TOKEN` for the session.\n\n## MCP client setup (local stdio)\n\nAn MCP client spawns the server itself — you register the command once and never run it\nby hand:\n\n```sh\nagkit mcp serve\n```\n\nIts stdout carries MCP protocol frames and nothing else; every diagnostic goes to stderr.\n\n### Claude Code\n\n```sh\nclaude mcp add agkit -s user -- agkit mcp serve\n```\n\n`-s user` is deliberate: a project-scope registration would follow one repository, while\nthis one provisions your machine.\n\n### Codex\n\nAdd to `~/.codex/config.toml`:\n\n```toml\n[mcp_servers.agkit]\ncommand = \"agkit\"\nargs = [\"mcp\", \"serve\"]\n```\n\n### Regenerating these snippets\n\nThe two blocks above show the generic `agkit` form, which pastes on any machine. To emit\nthem with the **absolute** path of the binary on *this* machine — what a client should\nactually register, so an nvm/fnm `PATH` change cannot break it — run:\n\n```sh\nagkit mcp print-config\n```\n\nThe command writes nothing; `agkit setup` is what edits client configs. Machine-readable:\n`agkit mcp print-config --json`.\n\nThe server implements MCP protocol revision **2026-07-28** (the `server/discover`\nhandshake) and still serves the legacy `initialize` handshake, negotiating down to\nany earlier revision a client requests.\n\n### Identity, credentials, and environment\n\nMCP registry identity, in the first-party namespace: `cloud.agkit/agkit`.\n\nThe local MCP server **reuses the CLI credential chain** described above — the same\nsingle seeded client (`agkit-cli`), the same precedence order, the same keychain entry.\nWhatever `agkit login` stored is what the server presents. Two consequences follow, both\nintentional:\n\n- There is **no separate stdio OAuth client** for MCP. Nothing to register, nothing to\n  keep in sync, no second credential to leak.\n- There is **no `agkit_login` MCP tool**. Logging in is a CLI-only action, so an MCP\n  host can spend your authority but can never mint, move, or widen it.\n\nThe four environment variables an MCP host may set for the server: `AGKIT_TOKEN`,\n`AGKIT_PROJECT`, `AGKIT_API_URL`, `AGKIT_PROFILE`.\n","readmeFilename":"README.md"}