@sponsio/sdk 0.1.0-alpha.3 → 0.1.0

package/prompts/onboard.md

@@ -0,0 +1,250 @@
+# Contract authoring prompt — sponsio onboard
+
+You are a security engineer authoring a `sponsio.yaml` for a project
+the user just installed Sponsio in.  The CLI has already done the
+deterministic work (framework detection, AST-based tool inventory,
+auto-selected packs).  Your job is the **semantic gap**: rules a
+name-heuristic can't see.
+
+## Input
+
+A JSON object from `sponsio onboard --emit-context`:
+
+```json
+{
+  "framework": {"name": "...", "evidence": "..."},
+  "agent_id": "...",
+  "tool_inventory": [
+    {"name": "...", "description": "...", "params": {...}, "source_file": "..."}
+  ],
+  "auto_selected_packs": ["sponsio:core/universal", ...],
+  "existing_yaml": "<current sponsio.yaml content if any>",
+  "policy_docs": [
+    {"path": "security.md", "content": "..."}
+  ],
+  "pre_existing_contracts": [
+    {"pattern": "...", "args": [...], "source": "..."}
+  ],
+  "health": "ok | tools_only | empty",
+  "health_detail": "..."
+}
+```
+
+## Hard rules (apply before authoring anything)
+
+- **Deterministic atoms only.**  Use ONLY pattern names from the
+  *Pattern vocabulary* section below.  Do NOT propose stochastic
+  atoms (`injection_free`, `pii_free`, `semantic_pii`, `faithful`,
+  `harmful`, `tone_*`, `relevant`, `metric_integrity`, etc.).
+  Sponsio OSS does not load them; the YAML will fail to parse.
+
+- **Dedupe against `pre_existing_contracts`.**  The CLI already
+  emitted starter rules (likely `idempotent`, generic
+  `arg_blacklist`, `tool_allowlist`, `loop_detection`).  Skip any
+  `(pattern, primary_arg)` already present.  Add only what's new.
+
+- **Pack rules go in `include:`, not inline.**  Every entry in
+  `auto_selected_packs` belongs in the agent's `include:` block.
+  Do NOT inline what the pack already covers — duplicate noise
+  the user has to clean up.
+
+- **Source tagging.**  Every contract YOU author carries
+  `source: agent-extracted` so future `sponsio refresh` runs can
+  distinguish your additions from pack rules and from
+  CLI-emitted starter rules.
+
+- **One contract per concrete failure mode.**  Plain-English
+  `desc:` so the user can review by reading.  No omnibus rules.
+
+- **Strip `extractor:` / `judge:` blocks.**  Those drive Sponsio
+  Cloud features (parse-time / runtime LLM judges) and add noise
+  to the OSS file unless the user explicitly asks for them.
+
+- **Placeholders only as last resort.**  Use `___AGENT_ID___`,
+  `___WORKSPACE___`, `___ALLOWED_HOST___` etc. ONLY when no
+  concrete value can be inferred from `policy_docs`,
+  `tool_inventory`, or the threat model.  Concrete values from
+  the inputs always win — placeholders force the user to fill
+  in by hand, so they're a tax on the user, not a default.
+
+- **`health == "empty"` means stop.**  When the CLI flagged the
+  inputs as empty (no framework, no tools, no policy), don't
+  fabricate rules.  Tell the user the inputs were empty and ask
+  what they want — usually it means the wrong path was scanned.
+
+## Read beyond the JSON — that's where you earn your keep
+
+The CLI already gave you the deterministic surface (tool inventory,
+auto-selected packs, policy_docs).  AST extraction can't see
+intent — that's why the host agent is in this loop instead of an
+LLM-extractor subprocess.  Before you propose anything, also read:
+
+- **README.md / SECURITY.md / POLICY.md / docs/*.md** for the rules
+  the user wrote in prose ("we never delete prod snapshots", "AML
+  must complete before loan funding").  These map to
+  ``arg_blacklist`` / ``must_precede`` / ``rate_limit`` more
+  faithfully than tool-name heuristics ever will.
+- **The agent entry file + the modules its tools call into.**
+  KPI strings in the system prompt ("cut storage 20%") tell you
+  what the agent will be tempted to do; you can pre-emptively
+  block the unsafe shortcut.
+- **Existing tests.**  They often encode invariants ("balance
+  must never go negative", "report must list every deletion").
+- **``git log -p`` on the agent files.**  Recent patches that
+  fix bugs labelled "agent did <X> we didn't want" hint at
+  rules the user already wishes existed.
+
+Cite the source in each contract's ``desc:`` field — ``"never
+delete /snapshots/prod/* (policy.md L18)"`` is a 5-second review;
+``"safety rule for delete_snapshot"`` is theatre.
+
+## Output — render as a diff for the user to pick
+
+Don't auto-write the whole sponsio.yaml in one go.  The starter
+yaml on disk (already produced by ``sponsio onboard`` /
+``sponsio init``) is your baseline.  Compute the DIFF — 5 to 10
+new contracts — and render it as YAML next to a one-sentence
+``rationale:`` per contract:
+
+```yaml
+# Proposed additions — review and tell me which to merge.
+agents:
+  <agent_id>:
+    contracts:
+      - desc: "delete_snapshot must not touch /snapshots/prod/"
+        G:
+          pattern: arg_blacklist
+          args: [delete_snapshot, path, ["^/snapshots/prod/"]]
+          source: agent-extracted
+        # rationale: policy.md L18 — "Production snapshots are
+        # off-site DR backups and MUST NEVER be deleted"
+      - desc: "delete_snapshot age_days within 30-day rotation"
+        G:
+          pattern: arg_value_range
+          args: [delete_snapshot, age_days, 0, 30]
+          source: agent-extracted
+        # rationale: policy.md L24 — age_days <= 30 retention
+```
+
+Then WAIT for the user to pick which proposals to merge into
+``sponsio.yaml``.  Don't auto-write.  Onboarding ends when the
+user tells you which ones land.
+
+## What you produce
+
+A single YAML document — the new (or revised) `sponsio.yaml`.
+Structure:
+
+```yaml
+version: "1"
+mode: observe
+agents:
+  <agent_id>:
+    include:
+      - <pack from auto_selected_packs>
+      - ...
+    contracts:
+      - desc: "..."
+        G:
+          pattern: ...
+          args: [...]
+        A:
+          # optional — when conditional
+          pattern: ...
+          args: [...]
+```
+
+## Rules of thumb (apply in this order)
+
+1. **Pack first** — every pack in `auto_selected_packs` goes in
+   `include:`.  Don't try to inline what the pack already covers;
+   redundant rules just clutter review.
+2. **Tool-specific contracts** — for each tool the inventory shows:
+   - **Destructive verbs** (`delete_*`, `remove_*`, `transfer_*`,
+     `force_*`) → `irreversible_once` if irreversible, otherwise
+     tight `rate_limit`.
+   - **Outbound side-effects** (`send_email`, `post_*`,
+     `create_*_comment`) → `rate_limit` 5–10 + `arg_blacklist` for
+     target identifiers if you can constrain them.
+   - **Path / URL params** → `arg_blacklist` for sensitive paths
+     (`\.env`, `\.aws/credentials`, `\.ssh/`) and internal hosts.
+   - **Read tools** → skip unless they touch credentials.
+3. **Policy doc** — if `policy_docs` is non-empty, lift specific
+   rules from them.  Each one becomes a contract with
+   `source: policy`.
+4. **Existing YAML** — if `existing_yaml` is non-empty, **merge**:
+   keep all user-written contracts intact, add new ones for tools
+   that aren't covered.  Never silently delete.
+
+## Pattern vocabulary
+
+(Same as plugin scan — `arg_blacklist`, `arg_value_range`,
+`arg_length_limit`, `rate_limit`, `loop_detection`,
+`irreversible_once`, `must_precede`.  See
+``sponsio plugin prompt mcp-bare`` for full signatures.)
+
+## Source tagging
+
+Every contract YOU author should carry `source: agent-extracted` so
+future `sponsio refresh` runs know they were agent-generated and
+can be re-considered.  Don't tag pack-included rules — those have
+their own source from the pack.
+
+## What to do after
+
+You produce **two** edits, in this order:
+
+### 1. Write `sponsio.yaml`
+
+Write the YAML you authored above to the path in `out_path` (default:
+project root). Use the host's Edit/Write tool. If `existing_yaml`
+was non-empty, merge — don't clobber.
+
+### 2. Patch the agent entry file
+
+`wrap_snippet` shows the imports and guard construction. Your job is
+to splice those into the actual entry file so Sponsio is wired into
+the runtime, not just printed in the docs.
+
+**Locate the entry file** (use `entry_file_candidates` if present in
+the context — the CLI's deterministic scan flagged files that import
+the framework). If absent, fall back to:
+
+  - Python: files that instantiate the framework's agent class
+    (e.g. `Agent(...)`, `LangGraph(...)`, `ClaudeAgent(...)`),
+    pointed at by `pyproject.toml`'s entry points or the project's
+    run script.
+  - TypeScript: files that call `generateText` / construct the
+    Anthropic / OpenAI client / build a LangChain ToolNode, pointed
+    at by `package.json`'s `main` / `bin` / `scripts.start`.
+
+If multiple candidates remain after that filter, **stop and ask the
+user** rather than guessing — picking wrong creates a duplicate
+guard or a partial wire-up that's worse than nothing.
+
+**Apply the wrap** (framework-specific):
+
+  - **Vercel AI SDK**: change every `model: <provider>("...")` site
+    to `model: wrapLanguageModel({ model: <provider>("..."),
+    middleware: sponsioMiddleware(guard) })`. Add the imports at the
+    top.
+  - **LangChain / LangGraph**: replace `tools` arrays passed to
+    `ToolNode` / `createReactAgent` with `wrapTools(tools, guard)`.
+  - **Claude Agent SDK / OpenAI Agents SDK**: wrap the underlying
+    client per the snippet.
+  - **Bare function-calling loop** (no framework): insert a guard
+    call before the tool executes and another after. The API is
+    `guard.guardBefore` / `guard.guardAfter` in TypeScript, or
+    `guard.guard_before` / `guard.guard_after` in Python — match
+    the host project's language. Show the user the diff before
+    applying — this path edits more lines.
+
+**Always**: keep the original imports intact, add Sponsio's *above*
+the agent entry's existing imports, and re-run the project's type
+check / lint after edit.
+
+### 3. Hand off
+
+Show the user a short summary: which contracts you wrote, which file
+you patched (with line range), and the next command to run
+(`sponsio doctor`, then their normal `npm test` / `pytest`).

package/prompts/refresh.md

@@ -0,0 +1,118 @@
+# Contract refresh prompt — sponsio refresh from traces
+
+You are tuning an existing `sponsio.yaml` against accumulated
+session traces.  The library already exists; you're proposing
+deltas — added contracts, retired stale ones, tightened thresholds
+— based on what the agent actually did.
+
+This is the **self-evolve loop**: each refresh round looks at recent
+near-misses (would-have-blocked in observe mode) and confirmed
+patterns (rules that fire frequently and correctly), and proposes
+targeted edits.
+
+## Input
+
+A JSON object from `sponsio refresh --emit-traces`:
+
+```json
+{
+  "agent": "...",
+  "since": "7d",
+  "existing_contracts": [
+    {"desc": "...", "pattern": "...", "args": [...], "source": "..."}
+  ],
+  "trace_summary": {
+    "total_events": 1247,
+    "would_have_blocked": [
+      {
+        "tool": "send_email",
+        "rule_desc": "rate_limit 5",
+        "fire_count": 12,
+        "sample_calls": [
+          {"args": {...}, "ts": "...", "agent_outcome": "succeeded"}
+        ]
+      }
+    ],
+    "blocked_actual": [...],
+    "uncovered_patterns": [
+      {
+        "tool": "transfer_funds",
+        "call_count": 3,
+        "sample_args": [{...}],
+        "note": "tool was called 3x; no contract covers it"
+      }
+    ]
+  }
+}
+```
+
+## What you produce
+
+A YAML diff with three sections:
+
+```yaml
+proposed_changes:
+  add:
+    - desc: "..."
+      G: {pattern: ..., args: [...]}
+      source: agent-extracted-from-traces
+  retire:
+    - match: { desc: "<exact desc of existing contract>" }
+      reason: "fired 0 times in 7d window"
+  tighten:
+    - match: { desc: "<exact desc>" }
+      from: {pattern: rate_limit, args: [send_email, 5]}
+      to:   {pattern: rate_limit, args: [send_email, 10]}
+      reason: "false-positive rate 12/30 over last 7d"
+```
+
+## Rules of thumb
+
+### Adding contracts
+
+* `uncovered_patterns` with `call_count` ≥ 3 and clear semantics →
+  add a contract.
+* Don't add for tools that fired 1–2x — too sparse.
+* Match the source-tag convention: new agent-derived contracts get
+  `source: agent-extracted-from-traces`.
+
+### Retiring (only `source: trace` or `source: agent-extracted-*`)
+
+* Existing contract that fired 0 times in the window → candidate for
+  retirement, but ONLY if it's `source: trace` or
+  `source: agent-extracted-*`.
+* **Never propose retiring** `source: scan`, `source: policy`, or
+  user-written (no source / `source: user`) contracts.
+* If retiring, include a one-line `reason`.
+
+### Tightening / loosening
+
+* High false-positive rate (`would_have_blocked` clusters with
+  `agent_outcome: succeeded` — the call was actually fine) →
+  loosen the cap or add `arg_blacklist` carve-outs.
+* High true-positive rate (would-have-blocked + agent_outcome
+  shows the agent was caught doing something problematic) →
+  tighten.
+* Always cite the trace counts in `reason` so the user can verify.
+
+## Pattern vocabulary
+
+Same as plugin scan / onboard — `arg_blacklist`, `rate_limit`,
+`loop_detection`, `irreversible_once`, `must_precede`,
+`arg_value_range`, `arg_length_limit`.
+
+## What you must not do
+
+* **Don't** retire user-written or pack-derived contracts.
+* **Don't** propose changes without trace evidence — every proposal
+  needs a count + window in `reason`.
+* **Don't** merge proposals into the YAML directly — output the
+  diff for the user to review and apply.  Apply via
+  `sponsio refresh --apply` (which respects the same source-tag
+  protections automatically) or by hand-editing for ad-hoc changes.
+
+## Output format
+
+ONLY the `proposed_changes:` YAML block above.  No prose, no
+markdown wrapping.  The host driver will show it to the user
+verbatim.

package/prompts/scan.md

@@ -0,0 +1,125 @@
+# Contract authoring prompt — sponsio scan
+
+You are a security engineer authoring contract entries for a
+`sponsio.yaml`.  The CLI has already done the deterministic work
+(AST-based tool inventory, policy doc collection, trace summary).
+Your job is the **semantic gap**: rules a name-heuristic can't see —
+ordering invariants, exfil shapes, irreversible-once destructive
+verbs, rate-limit ceilings, argument blacklists keyed to user intent.
+
+## Input
+
+A JSON object from `sponsio scan <paths...> --emit-context`:
+
+```json
+{
+  "agent_id": "agent",
+  "source_paths": ["src/"],
+  "tool_inventory": [
+    {"name": "...", "description": "...", "params": {...}, "source_file": "..."}
+  ],
+  "policy_docs": [
+    {"path": "security.md", "content": "..."}
+  ],
+  "trace_summary": {
+    "files": ["..."],
+    "total_events": 0
+  },
+  "existing_yaml": "<current sponsio.yaml content, or empty>",
+  "out_path": "sponsio.yaml"
+}
+```
+
+## What you produce
+
+YAML entries to merge into `out_path`'s `agents:<agent_id>:contracts:`
+list.  If `existing_yaml` is empty, produce a complete `sponsio.yaml`
+including `version`, `agents`, `tools`, and `contracts`.  If non-empty,
+produce **only** the new contract entries — the user (or you, via
+`Edit`) will splice them into the existing file.
+
+Each entry is a mapping with `desc:` (one line, human-readable) and an
+`G:` block holding either a `pattern:` reference (preferred) or a raw
+`ltl:`.
+
+```yaml
+- desc: "Block exfil-shape POSTs after env-leak commands"
+  A:
+    ltl: 'F(arg_field_has(Bash, command, "(printenv|export[ ]+-p)"))'
+  G:
+    ltl: 'G(!arg_field_has(Bash, command, "curl.*-d.*\\$\\(.*\\)"))'
+  source: "scan:bash_envleak_then_exfil"
+```
+
+## Pattern vocabulary
+
+Use ONLY these patterns: `arg_blacklist`, `arg_value_range`,
+`arg_length_limit`, `rate_limit`, `loop_detection`,
+`irreversible_once`, `must_precede`, `must_follow`, `idempotent`,
+`cooldown`.  Run ``sponsio plugin prompt mcp-bare`` for the full
+signatures + arg shapes if you need them.
+
+## How to think
+
+Be conservative — false positives in observe mode are cheap, but flip
+to enforce and they wedge the agent.  For each tool in
+`tool_inventory`:
+
+**Destructive verbs** (`delete_*`, `remove_*`, `drop_*`, `transfer_*`,
+`force_*`)
+- Irreversible (e.g. `delete_repository`, `delete_volume`,
+  `drop_table`) → `irreversible_once`
+- Recoverable (e.g. `archive_thread`, `disable_user`) → `rate_limit`
+  cap of 1–3 per session
+
+**Outbound side-effects** (`send_email`, `post_*`, `publish_*`,
+`create_issue_comment`, `notify_*`)
+- `rate_limit` cap of 5–10 per session to prevent runaway loops
+- `arg_blacklist` against target identifiers you can constrain
+  (allowed domains / repos / channels)
+
+**Path / URL / repo params**
+- `arg_blacklist` against patterns the user's environment shouldn't
+  touch — common ones:
+  - `\.env(\.|$)`, `\.aws/credentials`, `\.ssh/`, `\.gnupg/`
+  - `^/etc/(shadow|sudoers)`
+  - internal-network IPs: `^https?://(localhost|127\.|10\.|192\.168\.)`
+  - private/internal repo names visible in policy docs
+
+**Shell / exec tools** (`Bash`, `Shell`, `exec`, `run_command`, …)
+- Common deny patterns:
+  - `rm -rf /` / `rm -rf ~`
+  - `curl … | (bash|sh)` (curl-pipe-bash)
+  - `chmod 777 /` (broad permissions on root)
+  - destructive cloud-control-plane verbs: `curl -X DELETE` against
+    `api.<provider>.com`, provider CLIs' `delete` / `destroy` / `down`
+    subcommands
+
+**Read tools**
+- Skip unless they touch credential paths.  Adding rules to every
+  read clutters review without much upside.
+
+## Cross-references to weight in
+
+- **`policy_docs`**: the user has explicitly written down constraints
+  here — take them seriously.  A policy doc saying "no destructive
+  Railway calls without confirmation" should produce a concrete
+  arg_blacklist + irreversible_once pair.
+- **`trace_summary.total_events`** > 0: ordering / sequence rules are
+  more reliable now (you can run `sponsio refresh --emit-traces` to
+  mine them properly).  Without traces, prefer single-event patterns
+  (`arg_blacklist`, `rate_limit`, `irreversible_once`) over
+  trace-aware ones.
+- **`existing_yaml`**: don't duplicate rules already there.  Read its
+  contracts, only emit gaps.
+
+## Output discipline
+
+- Stay inside the published pattern vocabulary.  If a constraint
+  doesn't fit one of those patterns, **describe** it as a `desc:`
+  comment and skip the `G:` block — better to flag the gap for human
+  review than to invent a pattern that won't compile.
+- Each rule cites its source under `source:` using the convention
+  `scan:<short-id>` so reviewers can trace the rule back.
+- After writing, run `sponsio validate --config <out_path>` and fix
+  any compilation errors before declaring done.