Skip to content
Back to search

upstream-agents-plugin

MarketplaceWorks with Claude CodeGitHub

Upstream drilling and well-lifecycle advisory agents: 17 agent contracts, 10 skills and a deterministic advisory MCP. Advisory only — never actuates.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/albanc80--upstream-agents-plugin/badge.svg)](/listings/albanc80--upstream-agents-plugin)

HTML

<a href="/listings/albanc80--upstream-agents-plugin"><img src="/api/listings/albanc80--upstream-agents-plugin/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

See [docs/INSTALL.md](docs/INSTALL.md). Verified against the real clients:

# Hermes
hermes plugins install albanc80/upstream-agents-plugin && hermes plugins enable upstream-agents-plugin

# Codex — the repo declares itself as a marketplace (.claude-plugin/marketplace.json)
codex plugin marketplace add albanc80/upstream-agents-plugin
codex plugin add upstream-agents-plugin@upstream-agents-plugin

# Claude Code
/plugin install upstream-agents-plugin --marketplace albanc80/upstream-agents-plugin

Or from a working copy, without installing: `hermes plugins install .`, `claude --plugin-dir .`.

The repository is public: no token or GitHub identity is needed. The plugin's tools need [`uv`](https://docs.astral.sh/uv/) on `PATH`; dependencies are declared inside the server script and resolved on first run — see [First run](docs/INSTALL.md).

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 20 lines
  1. {
  2. "name": "upstream-agents-plugin",
  3. "owner": {
  4. "name": "Alberto Ancona"
  5. },
  6. "interface": {
  7. "displayName": "Upstream Agents Plugin"
  8. },
  9. "plugins": [
  10. {
  11. "name": "upstream-agents-plugin",
  12. "source": "./",
  13. "category": "engineering",
  14. "policy": {
  15. "installation": "AVAILABLE",
  16. "authentication": "ON_INSTALL"
  17. }
  18. }
  19. ]
  20. }
README.md · README · 251 lines
  1. # Upstream Agents Plugin
  2. A portable **[Agent Plugins v1](https://agent-plugins.org)** package carrying upstream drilling
  3. and well-lifecycle advisory agents, derived from a private reference implementation.
  4. **Advisory only.** Nothing here commands a rig, a BOP or a choke, and nothing writes a setpoint.
  5. Every numeric recommendation is expected to come from the deterministic advisory server, not
  6. from a model's own arithmetic.
  7. ## What it does
  8. Nine advisory domains across the well lifecycle, one deterministic engine behind them. It reads
  9. telemetry, scores it, applies thresholds, and tells you what the numbers mean and what is allowed.
  10. It never touches the rig.
  11. ### What you can ask it
  12. | Ask about | You get | Skill |
  13. |---|---|---|
  14. | Influx, gain, losses, SIDPP, MAASP, kill sheet | Alert level and fused probability, kick/loss class, MAASP, kill MW, ICP, FCP | `well-control-guard` |
  15. | Drag, torque, overpull, a string that will not move | 0–100 risk score, mechanism, intervention, movement veto | `stuck-pipe-prevention` |
  16. | ROP, MSE, founder point, vibration | MSE, founder-point call, envelope-checked WOB/RPM change | `drilling-optimization` |
  17. | ECD, hole cleaning, mud weight, surge and swab | ECD against the window, transport ratio, margins | `hydraulics-and-fluids` |
  18. | Surveys, DLS, toolface, collision, landing | DLS and min-curvature position, separation factor, target position | `directional-and-geosteering` |
  19. | Casing design, cement job, bond log, wireline | Design factors, placement vs isolation, bond index | `well-construction` |
  20. | Perforation, stages, lift, decline, integrity | Stage and cluster checks, screenout, loading, decline, SCP | `completions-and-production` |
  21. | Channels, units, mnemonics, timestamps | Six-check quality score and the specific defect | `data-quality-and-standards` |
  22. | Who may act, conflicting advice, audit trail | Tier precedence, veto outcome, routing, chained record | `agentic-coordination` |
  23. | Anything spanning several domains | One specialist, chosen after the quality gate | `upstream-ops` |
  24. ### What it identifies
  25. **Influx and losses.** A kick or loss on a five-step ladder — Normal, Monitor, Advisory, Well
  26. Control Alert, Emergency Shut-In Proposal — fused from pit gain, flow differential, gas and the PWD
  27. residual. Classifies `GAS_KICK`, `WATER_KICK` or `LOST_CIRCULATION`, and level 3 upward flags
  28. regulatory notification. Bands: probability 0.20 / 0.40 / 0.60 / 0.85, pit gain above 2 bbl
  29. advisory, above 5 bbl emergency.
  30. **Stuck pipe.** A 0–100 risk score from torque excess (0.40), overpull (0.30), overbalance (0.20)
  31. and inclination (0.10), banded at 25 advisory, 40 active, 60 immediate, 80 critical. Names the
  32. mechanism — differential sticking, pack-off, key seat, collapse — and above 60 it vetoes any WOB
  33. increase, offering WOB −3 klbs and RPM +10 instead.
  34. **Hole cleaning and hydraulics.** Cuttings transport ratio below 0.55 is a problem and below 0.40 a
  35. deficit; slip velocity 45 ft/min; ECD warning at 90% of fracture gradient and critical at 95%. The
  36. mud weight window wants 0.2 ppg overbalance and a 0.3 ppg ECD-to-gradient margin.
  37. **Drilling performance.** Teale MSE and the founder point: rising MSE at flat ROP means additional
  38. weight is buying heat, not hole. Changes below 2% are not worth making; vibration above 0.7 is
  39. dysfunction, not optimisation.
  40. **Trajectory.** DLS against a 5.0 deg/100 ft limit, position by minimum curvature rather than
  41. interpolation, 5 ft minimum survey spacing, well separation factor caution at 1.5 with a mandatory
  42. stop at 1.0, 25 ft collision boundary.
  43. **Tubulars and cement.** Design factors of 1.10 burst, 1.00 collapse and 1.30 tension, with drag
  44. above 15% of model as an alert. Cement: density channeling at 0.5 ppg or 10% of pressure, job
  45. pressure 200 psi over design, zonal isolation 0.70 to pass and 0.50 to fail, bond index 0.80 good
  46. and 0.60 marginal.
  47. **Completions and production.** Isolation gate of 0.70, at most 5 clusters per stage at 40 ft
  48. spacing, screenout on a 500 psi/min rise sustained over 3 readings, MAOP alert at 95%, liquid
  49. loading against a 1.2 Turner factor, sustained casing pressure flagged at 30 psi rising to 100 psi,
  50. reforecast when EUR moves 20%.
  51. **Formation evaluation.** Net-pay screens: water saturation at or below 0.65, porosity at least
  52. 0.08, resistivity at least 20 ohm·m, shows where Sw is at or below 0.5.
  53. **Data defects.** Six checks — physical bounds, sequence, redundancy drift, outliers, completeness
  54. and voting — collapsed into one 0–1 score. Below 0.95 the sample is not actionable, and the correct
  55. answer becomes the defect rather than the value.
  56. **Conflicts and authority.** Which proposal wins by tier, which vetoes were raised, what safer
  57. alternative was generated, whether a human must confirm, and a hash-chained record of the decision.
  58. ### What it computes
  59. 31 formulas behind one tool, so no client does the arithmetic itself: pressure gradient,
  60. hydrostatic pressure, mud weight from pressure, buoyancy, ECD, MAASP, mud weight window, kick
  61. tolerance, kill mud weight, formation pressure, ICP, FCP · pipe and annular capacity, annular
  62. velocity, cuttings transport · Teale MSE · dogleg angle and severity, minimum curvature · Vshale,
  63. density porosity, Archie saturation · casing wall thickness, Barlow burst, API collapse, body yield
  64. · CBL bond index · Turner critical velocity, Arps hyperbolic decline.
  65. ### Who decides
  66. 17 agent contracts in four tiers: **3 safety** (well control, PWD, MWD), **12 NPT** (casing,
  67. cementing, completions, fluids, geosteering, hydraulics, LWD, production, stimulation, stuck pipe,
  68. well planning, wireline), **1 performance** (directional steering) and **1 cost** (drilling
  69. optimisation). The lower tier wins a conflict; safety outranks confidence.
  70. ### What it will not do
  71. - **No actuation.** No BOP, choke, pump or setpoint command exists anywhere in the package.
  72. - **No safety verdict from prose.** The gates are tools; a skill that skips one is a defect.
  73. - **No invented thresholds.** Every number traces to a module and line in
  74. [`docs/THRESHOLDS-TRACE.md`](docs/THRESHOLDS-TRACE.md).
  75. - **No site limits.** `site_validated` stays false until a named well supplies real ones.
  76. ## Status
  77. | Phase | Scope | State |
  78. |---|---|---|
  79. | P0 | Manifest, two proof contracts, policies, provenance trace, validator | done |
  80. | P1 | All 17 contracts + 4 skills — installable package | done |
  81. | P2 | `servers/advisory_core` deterministic MCP + `mcp.json` | done |
  82. | P3 | Install verification in Hermes, Codex and Claude Code | done |
  83. | P4 | Remaining 6 skills | done |
  84. | P5 | Claude shim + marketplace, so clients install from the repo | done; OpenClaw untested |
  85. | P6 | CI, docs, example, security policy | done |
  86. | **Release** | **public, `v1.0.0` tagged** | **[docs/PUBLIC-RELEASE.md](docs/PUBLIC-RELEASE.md)** |
  87. ## What is in the package
  88. ```
  89. plugin.json Agent Plugins v1 manifest
  90. mcp.json declares the advisory-core stdio server
  91. skills/ 10 Agent Skills (SKILL.md + references)
  92. src/agents/ 17 agent contracts: tier, veto, thresholds, citations
  93. src/policies/ safety envelope, veto matrix, never-do list, site defaults
  94. servers/advisory_core deterministic advisory spine — 11 MCP tools, 31 formulas
  95. tests/ 50 tests: engine parity, behaviour, README-claim guard
  96. examples/ gas-influx walkthrough — 18 asserted values, runs in CI
  97. docs/ INSTALL, BOUNDARIES, THRESHOLDS-TRACE, PUBLIC-RELEASE
  98. tools/validate.py manifest + contract + skill + provenance gate
  99. .claude-plugin/ Claude shim + marketplace.json (Codex reads it too)
  100. .github/workflows/ CI: validate, tests, walkthrough, selftest, schema
  101. LICENSE · NOTICE Apache-2.0 + engineering safety notice
  102. SECURITY.md what to report, and how
  103. ```
  104. ## Advisory tools
  105. `list_capabilities`, `list_channels`, `list_formulas`, `compute`, `qse_score_sample`,
  106. `check_safety_envelope`, `route_autonomy`, `negotiate`, `well_control_assess`, `audit_append`,
  107. `audit_trace`.
  108. They read their thresholds from the packaged contracts, so a tool and the skill that cites it
  109. cannot disagree. `compute` covers 31 formulas transcribed verbatim from the engine, including MAASP,
  110. kill-mud weight, ICP/FCP, ECD, MSE, dogleg and minimum curvature, casing burst/collapse/tension,
  111. CBL bond index and Arps decline.
  112. ## Harness support
  113. The package is portable, but *portable* is not the same as *every client*. What matters is whether
  114. the harness can spawn a **local stdio process**, because that is how the advisory tools are served.
  115. | Harness | Skills | Advisory tools | Path |
  116. |---|---|---|---|
  117. | **Hermes** | yes | yes | `hermes plugins install` — verified |
  118. | **Codex** | yes | yes | `codex plugin marketplace add` + `plugin add` — reads `mcp.json`, verified |
  119. | **Claude Code** | yes | yes | `.claude-plugin/` shim, `claude plugin validate` passes, verified |
  120. | **OpenClaw** | v1 client | expected | bundles path — not exercised here |
  121. | **Copilot / Cursor / VS Code / Kiro** | v1 clients | client-dependent | they install the package; spawning the stdio server is their setting |
  122. | **ChatGPT desktop / Codex runtime** | yes | yes | MCP entry in `~/.codex/config.toml` — verified in a live session |
  123. | **chatgpt.com, ChatGPT mobile** | no | no | no local process; needs a remote HTTPS MCP endpoint |
  124. **The dividing line is whether the surface runs a local process**, not whose brand is on it. Anything
  125. running the Codex runtime — Codex CLI or the ChatGPT desktop app — hosts the bundled server; register
  126. it once in `~/.codex/config.toml` (see [docs/INSTALL.md](docs/INSTALL.md)). A browser tab or a phone
  127. cannot, so on chatgpt.com you get a competent qualitative answer with no deterministic verdict — and
  128. that is the design working, not a defect:
  129. > The advisory server was unavailable, so no data-quality score, formal alert level, kick
  130. > probability, or validated kill-sheet values were produced.
  131. Every skill is written to say exactly that rather than invent a threshold. Putting the tools in a
  132. browser session means hosting the server as a remote MCP endpoint with authentication — a deployment
  133. and security decision, not a packaging one.
  134. ## Install
  135. See [docs/INSTALL.md](docs/INSTALL.md). Verified against the real clients:
  136. ```bash
  137. # Hermes
  138. hermes plugins install albanc80/upstream-agents-plugin && hermes plugins enable upstream-agents-plugin
  139. # Codex — the repo declares itself as a marketplace (.claude-plugin/marketplace.json)
  140. codex plugin marketplace add albanc80/upstream-agents-plugin
  141. codex plugin add upstream-agents-plugin@upstream-agents-plugin
  142. # Claude Code
  143. /plugin install upstream-agents-plugin --marketplace albanc80/upstream-agents-plugin
  144. ```
  145. Or from a working copy, without installing: `hermes plugins install .`, `claude --plugin-dir .`.
  146. The repository is public: no token or GitHub identity is needed. The plugin's tools need
  147. [`uv`](https://docs.astral.sh/uv/) on `PATH`; dependencies are declared inside the server script and
  148. resolved on first run — see [First run](docs/INSTALL.md).
  149. ## Harnesses without MCP registration
  150. The tools are also callable from a shell, through the same engine and the same refusals. Useful
  151. where MCP is unavailable, misconfigured, or hosted in a surface that cannot spawn a process:
  152. ```bash
  153. uv run --script servers/advisory_core/main.py --list-tools
  154. uv run --script servers/advisory_core/main.py --call well_control_assess \
  155. '{"pit_gain_bbl": 4, "flow_diff_gpm": 12, "gas_units_pct": 3.5}'
  156. ```
  157. It prints the JSON the MCP tool would return, and exits non-zero on a refusal or bad arguments
  158. rather than answering anyway. The skills use this path before falling back to prose, so an agent
  159. without a working MCP connection still gets deterministic values instead of an estimate.
  160. ## Try it
  161. [`examples/`](examples/) holds one worked scenario — a gas influx on a 12¼ in section while the
  162. optimisation agent is still asking for more weight on bit — with 18 asserted values:
  163. ```bash
  164. uv run --script examples/run_walkthrough.py # expect: PASSED — 18 checks
  165. ```
  166. It boots the real MCP server over stdio, so it doubles as the integration test and fails on any
  167. drift. [`examples/README.md`](examples/README.md) also gives the three client-side prompts worth
  168. pasting into Hermes, Codex or Claude, and the anti-patterns that mean a client is bluffing.
  169. ## Verify
  170. ```bash
  171. python tools/validate.py # expect PASS 0 failures
  172. uv run --with pytest --with pyyaml -- python -m pytest tests -q # expect 50 passed
  173. uv run --script servers/advisory_core/main.py --selftest # expect 5 [OK] lines
  174. hermes plugins validate . # portable v1 accepted
  175. ```
  176. ## Reading order
  177. 1. [docs/BOUNDARIES.md](docs/BOUNDARIES.md) — what this refuses to do, and the model gaps.
  178. 2. [docs/THRESHOLDS-TRACE.md](docs/THRESHOLDS-TRACE.md) — every number and its source line.
  179. 3. `src/agents/*.yaml` — the contracts, including `known_gaps` per agent.
  180. ## Contract rules
  181. 1. **Numbers are transcribed, never tuned.** Every threshold cites an engine module and line in
  182. `docs/THRESHOLDS-TRACE.md`. To change a value, change the reference implementation and re-extract.
  183. 2. **Known gaps are recorded, not smoothed over.** Where the reference implementation does not do what
  184. its spec claims, `known_gaps` says so, and the discrepancies found so far are recorded in
  185. `src/policies/veto-matrix.yaml`.
  186. 3. **Guarantees live in tools, not prose.** A skill that *explains* the safety envelope without
  187. invoking it is a liability.
  188. 4. **Site values are not shipped as truth.** `src/policies/site-defaults.yaml` is flagged
  189. `site_validated: false` until a named well or field provides real limits.
  190. ## Licence
  191. Apache License 2.0 — see `LICENSE` and `NOTICE`. The package includes an engineering safety notice: it is decision
  192. support, not a control system, and outputs must be verified against the applicable drilling programme before use.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.