@ssheleg/agent-stack 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,90 @@
+# Changelog
+
+All notable changes to this project are documented here.
+Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+Versioning: [SemVer](https://semver.org/spec/v2.0.0.html).
+
+## [0.3.0] — 2026-08-12
+
+### Changed
+
+- **The description now opens with `Use when …` and carries paired Russian triggers.**
+  That has been the family canon since `super-ux` v0.20.0; this repository was created
+  after it and never adopted it, so the skill did not match a request written in
+  Russian — and a skill that does not match is a skill that is not there. 923/1024
+  chars, inside the 970 working limit that v0.2.0 had already brought it under.
+
+## [0.2.0] — 2026-08-11
+
+### Changed
+
+- **The body went 604 lines / 5361 tokens to 459 / 4146** — the caps are 500
+  and 5000, and it was the only skill in the family over both. Measured with
+  `cl100k`.
+
+  Sections 6 (provider routing) and 7 (memory layers) were carrying depth that
+  `references/llm-proxy-billing.md` and `references/patterns.md` already hold —
+  fallback chains and retry/backoff in the first, confidence management,
+  extraction heuristics, fuzzy deduplication and conflict resolution in the
+  second. The body keeps the shape of each (the four-layer table, the router's
+  contract) plus the traps, and points at the depth.
+
+  The traps stay inline because an agent cannot know to open a file about a
+  trap it does not know exists: a retry loop and a fallback chain **multiply**,
+  a health check that only runs on failure never recovers, model selection has
+  three levels and a silent precedence bug bills a cheap model at a premium
+  rate, and every memory layer competes for one context window — give layer 1 a
+  floor or old generalities crowd out what the user said a minute ago.
+
+- `references/patterns.md` gains the `## Contents` list the canon requires of a
+  reference over 100 lines: a partial read is what agents actually do, and
+  without the list it returns an arbitrary slice.
+
+- The description trimmed 975 → 937 chars, inside the 970 headroom, by dropping
+  two trigger phrases already covered by their neighbours.
+
+## [0.1.0] — 2026-08-06
+
+First release. The skill is a port: it was written and used inside Cursor
+against a production multi-agent system, and this repository is where it
+becomes installable, versioned and checked.
+
+### Added
+
+- **`agent-orchestrator` skill** (618 lines) — the orchestrator pattern with a
+  shared context object and a sub-agent protocol; a tool-calling loop with
+  in-loop trimming, wrap-up injection at ~70% of the window and a max-iteration
+  guard that still composes a partial answer; meta-tools that delegate rather
+  than execute; sub-agent retry split into retryable and fatal; a multi-stage
+  pipeline with complexity detection, human-in-the-loop checkpoints and resume;
+  multi-provider routing with fallback, exponential backoff and health checks;
+  a four-layer memory system (chat history, working memory, long-term learnings,
+  insights) with confidence lifecycles, fuzzy dedup, conflict resolution and
+  decay; context budget allocation; self-learning feedback loops.
+- **`references/patterns.md`** (351 lines) — the data models and algorithms
+  behind the above: message and result protocols, pipeline models, the SQL
+  validation loop, context-window sizes and token estimation, learning
+  extraction heuristics, confidence management, the fuzzy-dedup and
+  conflict-resolution patterns, cross-resource transfer, and a suggestion engine
+  that costs no LLM calls.
+- **`references/llm-proxy-billing.md`** (255 lines) — the wallet side of
+  reselling LLM access, generalized from an OpenRouter Management API
+  integration: tiered balances and the single boundary where markup applies,
+  two-phase commit against a provider API with compensating transactions,
+  transaction-scoped advisory locking, optimistic concurrency for reclaims,
+  spend-delta polling and the three cases it must distinguish, budget/loop/
+  auto-pause guardrails converging on one pause function with per-cause
+  timestamps, per-tenant key lifecycle and healing, the refund waterfall, and
+  model routing precedence.
+- Structural validator (`test/validate.py`) enforcing one version across four
+  files, Agent Skills front-matter limits, and reference links in **both**
+  directions — the source this skill came from shipped a `reference.md` that
+  nothing referenced, and that is now a failing check.
+- Installer CLI, `install.sh`, Cursor rule channel, plugin + marketplace
+  manifests, CI with negative self-tests.
+
+### Notes
+
+The `references/patterns.md` file was `reference.md` in the source and was
+renamed on the way in: it is loaded by name from `SKILL.md`, and the validator
+now requires that link to resolve.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ssheleg
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,107 @@
+# agent-stack
+
+Production patterns for building AI agent orchestrators — and for billing the
+LLM access they burn.
+
+Part of the [ssheleg skill family](https://github.com/ssheleg/sshlg-skills).
+
+---
+
+## What is in here
+
+One skill, `agent-orchestrator`, and two references it loads on demand.
+
+**The orchestrator** (`SKILL.md`) — what the agent reads first:
+
+- a shared context object and a sub-agent protocol with typed results
+- a tool-calling loop that survives its own context pressure: in-loop trimming
+  at ~80% of the window, a wrap-up instruction at ~70%, a max-iteration guard
+  that still composes a partial answer instead of returning nothing
+- meta-tools that **delegate to sub-agents** rather than execute directly
+- sub-agent retry split into retryable and fatal, with validation between tries
+- a multi-stage pipeline for complex work: complexity detection, checkpoints
+  where a human approves, and resume after they do
+- multi-provider LLM routing with a fallback chain, per-provider exponential
+  backoff that respects `retry_after`, health checks and one error hierarchy
+- a four-layer memory system — chat history, working memory, long-term
+  learnings, insights — each with its own lifetime, confidence lifecycle and
+  decay, plus conflict resolution when a new learning contradicts an old one
+- context budget allocation by priority
+- self-learning feedback loops
+
+**`references/patterns.md`** — the data models and algorithms underneath:
+message and result protocols, pipeline models, the SQL validation loop,
+context-window sizes and token estimation, learning-extraction heuristics,
+confidence management, fuzzy deduplication, conflict resolution, cross-resource
+learning transfer, and a suggestion engine that costs no LLM calls.
+
+**`references/llm-proxy-billing.md`** — for when the product resells LLM access:
+tiered wallets and the single boundary where markup applies, two-phase commit
+across a database and a provider API with compensating transactions,
+transaction-scoped advisory locking, optimistic concurrency for reclaims,
+spend-delta polling and the three cases it must tell apart, budget / loop /
+auto-pause guardrails, per-tenant key lifecycle and healing, the refund
+waterfall, and model-routing precedence.
+
+---
+
+## Install
+
+**Claude Code plugin** (recommended):
+
+```bash
+/plugin marketplace add ssheleg/agent-stack
+/plugin install agent-stack@agent-stack
+```
+
+**npm installer** — copies the skill into `~/.claude/skills/`:
+
+```bash
+npx @ssheleg/agent-stack
+```
+
+**Any of 70+ agents:**
+
+```bash
+npx skills add ssheleg/agent-stack
+```
+
+**Whole family at once:**
+
+```bash
+npx --yes sshlg-skills@latest update
+```
+
+Restart your agent afterwards — skills load at session start.
+
+---
+
+## When it triggers
+
+Building an agent system, an orchestrator, an LLM-powered tool, a chatbot with
+tool use, or an AI pipeline. Also when the work is the money side: metering
+usage, per-tenant keys, spend tracking, budget limits, loop detection.
+
+It does **not** trigger for a single LLM call in a script, or for prompt
+wording — that is not an orchestrator, and pulling 1200 lines of doctrine for it
+is how a skill teaches you to route around it.
+
+---
+
+## Verify
+
+```bash
+python3 test/validate.py
+```
+
+Checks one version across `package.json`, `plugin.json`, `marketplace.json` and
+the top `CHANGELOG` entry; front matter inside the Agent Skills limits (over-long
+front matter does not error — hosts truncate it silently, which is worse); and
+that `SKILL.md` and `references/` agree in **both** directions, so neither a
+dangling link nor a file nobody loads can ship.
+
+---
+
+## License
+
+MIT © ssheleg

package/SECURITY.md

@@ -0,0 +1,63 @@
+# Security
+
+## What this skill actually does on your machine
+
+`agent-stack` is documentation plus one small Python script. Installed, it is:
+
+| Component | Runtime behavior |
+|---|---|
+| `SKILL.md` + `references/*.md` | Text. Read by the agent, executes nothing. |
+| `scripts/page_audit.py` | Runs only when you or the agent invokes it. Python **standard library only** — no dependencies, no install step. |
+| `commands/`, `cursor/rules/` | Text read by the host agent. |
+| `bin/agent-stack.js` (npm installer) | Copies the skill directory and the slash command into `~/.claude/`. No network, no post-install script. |
+
+There is no telemetry, no analytics, no phone-home, and nothing writes outside
+the paths above.
+
+## Network behavior of `page_audit.py`
+
+- Plain `GET` requests, **http and https only** — any other scheme (`file://`,
+  `ftp://`, `gopher://`, …) is refused before a request is made, and a redirect
+  that leaves http(s) is refused too.
+- Only to URLs **you** pass via `--url` / `--url-list`. In `--file` mode it makes
+  no requests at all, which is how the test suite runs.
+- No cookies, no credentials, no auth headers; a plain User-Agent that identifies
+  the tool.
+- Bounded: `--timeout` (default 20s) and `--max-bytes` (default 5 MB). A declared
+  content type that is not HTML/XHTML/XML is refused rather than parsed.
+- Read-only: results go to stdout. The script never writes a file. The only files
+  it ever **reads** are the two you name yourself (`--file`, `--url-list`).
+
+## What the skill will not tell an agent to do
+
+The audit procedure is explicitly **defensive**. Manipulative tactics —
+cloaking, fabricated consensus networks, review manipulation, click-signal
+spoofing, takedown abuse — appear only in `references/threats-and-defense.md`,
+written as *detect and withstand*, and the skill's non-negotiables forbid
+recommending them.
+
+The procedure is also read-only by default: it will not submit forms, request
+indexing, disavow links or change a live property without explicit approval in
+the session.
+
+## Reporting a problem
+
+Open an issue at <https://github.com/ssheleg/agent-stack/issues>. If it is
+sensitive, say so in the issue without the details and a private channel will be
+arranged.
+
+## Verifying for yourself
+
+```bash
+git clone https://github.com/ssheleg/agent-stack && cd agent-stack
+python3 test/validate.py         # structure, version sync, references, links, anchors
+python3 test/test_page_audit.py  # auditor behavior, offline fixtures + scheme guard
+grep -rnE "urlopen|build_opener|opener\.open|socket|subprocess|os\.system|\beval\(|\bexec\(|\bopen\(" \
+  plugins/agent-stack/skills/agent-stack/scripts/page_audit.py
+```
+
+The last command prints the auditor's entire I/O surface — six lines: the
+`urllib.request` import, one comment, the opener that carries the scheme guard,
+the one `opener.open(...)` call, and the two `open()` calls that read the file
+paths you pass on the command line. No `subprocess`, no `os.system`, no `eval`,
+no `exec`, no raw sockets. Everything else in `plugins/` is markdown.

package/bin/agent-stack.js

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+/*
+ * agent-stack installer CLI.
+ *
+ * Installs the agent-orchestrator skill into ~/.claude/skills/agent-orchestrator
+ * (same layout as install.sh). Idempotent: an existing install is skipped unless
+ * --force. Zero dependencies.
+ *
+ * For other agents (Cursor, Codex, 70+) use: npx skills add ssheleg/agent-stack
+ */
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const ROOT = path.resolve(__dirname, '..');
+const REPO = 'ssheleg/agent-stack';
+
+function usage() {
+  console.log(`agent-stack installer
+
+Usage:
+  npx @ssheleg/agent-stack [--force]   install the agent-orchestrator skill
+                                       into ~/.claude (skip existing unless --force)
+  npx @ssheleg/agent-stack --help
+
+Other install paths:
+  Claude Code plugin:  /plugin marketplace add ${REPO}
+                       /plugin install agent-stack@agent-stack
+  Any agent (70+):     npx skills add ${REPO}`);
+}
+
+function copyDir(src, dest) {
+  fs.mkdirSync(dest, { recursive: true });
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const s = path.join(src, entry.name);
+    const d = path.join(dest, entry.name);
+    if (entry.isDirectory()) copyDir(s, d);
+    else fs.copyFileSync(s, d);
+  }
+}
+
+function installOne(label, src, dest, isDir, force) {
+  if (fs.existsSync(dest) && !force) {
+    console.log(`skip: ${label} already installed at ${dest} (rerun with --force to overwrite)`);
+    return;
+  }
+  fs.rmSync(dest, { recursive: true, force: true });
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  if (isDir) copyDir(src, dest);
+  else fs.copyFileSync(src, dest);
+  console.log(`Installed ${label} -> ${dest}`);
+}
+
+function main(argv) {
+  const args = argv.slice(2);
+  if (args.includes('--help') || args.includes('-h')) {
+    usage();
+    return 0;
+  }
+  const force = args.includes('--force');
+  const unknown = args.filter((a) => a !== '--force');
+  if (unknown.length) {
+    console.error(`unknown argument(s): ${unknown.join(' ')}`);
+    usage();
+    return 2;
+  }
+
+  const skillSrc = path.join(ROOT, 'plugins/agent-stack/skills/agent-orchestrator');
+  if (!fs.existsSync(skillSrc)) {
+    console.error(`error: skill sources missing at ${skillSrc} — corrupted package?`);
+    return 1;
+  }
+
+  const home = os.homedir();
+  installOne(
+    'agent-orchestrator skill',
+    skillSrc,
+    path.join(home, '.claude', 'skills', 'agent-orchestrator'),
+    true,
+    force
+  );
+  return 0;
+}
+
+process.exit(main(process.argv));

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@ssheleg/agent-stack",
+  "version": "0.3.0",
+  "description": "Production patterns for AI agent orchestrators — tool-calling loops, multi-stage pipelines with checkpoints, LLM provider routing with fallback, four-layer memory with confidence decay — plus the wallet side of reselling LLM access. This package is the installer CLI.",
+  "bin": {
+    "agent-stack": "bin/agent-stack.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "bin",
+    "plugins",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md",
+    "SECURITY.md"
+  ],
+  "repository": "github:ssheleg/agent-stack",
+  "homepage": "https://github.com/ssheleg/agent-stack",
+  "license": "MIT",
+  "author": {
+    "name": "ssheleg",
+    "url": "https://x.com/sshlg93"
+  },
+  "engines": {
+    "node": ">=16"
+  },
+  "keywords": [
+    "agent",
+    "orchestrator",
+    "llm",
+    "tool-calling",
+    "multi-agent",
+    "openrouter",
+    "llm-billing",
+    "claude-code",
+    "cursor",
+    "skill"
+  ]
+}

package/plugins/agent-stack/.claude-plugin/plugin.json

@@ -0,0 +1,24 @@
+{
+  "name": "agent-stack",
+  "displayName": "Agent Stack",
+  "description": "Production patterns for AI agent orchestrators: tool-calling loops, multi-stage pipelines with checkpoints, LLM provider routing with fallback, four-layer memory with confidence decay — plus the wallet side of reselling LLM access.",
+  "version": "0.3.0",
+  "author": {
+    "name": "ssheleg",
+    "url": "https://x.com/sshlg93"
+  },
+  "homepage": "https://github.com/ssheleg/agent-stack",
+  "repository": "https://github.com/ssheleg/agent-stack",
+  "license": "MIT",
+  "keywords": [
+    "agent",
+    "orchestrator",
+    "llm",
+    "tool-calling",
+    "multi-agent",
+    "openrouter",
+    "llm-billing",
+    "claude-code",
+    "cursor"
+  ]
+}