diff --git a/.github/workflows/augment-hooks.yml b/.github/workflows/augment-hooks.yml new file mode 100644 index 000000000..d9875eff2 --- /dev/null +++ b/.github/workflows/augment-hooks.yml @@ -0,0 +1,40 @@ +name: Auggie session hooks + +on: + pull_request: + paths: + - 'examples/coding-agents/augment-code/**' + - 'examples/coding-agents/hook-to-otlp/**' + - 'src/pages/docs/integrations/coding-agents/augment-code.mdx' + - 'scripts/augment-code-page.test.mjs' + - '.github/workflows/augment-hooks.yml' + workflow_dispatch: + +permissions: + contents: read + +jobs: + session-hooks: + name: Auggie hook contracts (${{ matrix.os }}) + runs-on: ${{ matrix.os }} + timeout-minutes: 15 + strategy: + fail-fast: false + matrix: + include: + - os: ubuntu-24.04 + python: '3.9' + - os: macos-26 + python: '3.13' + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-python@v5 + with: + python-version: ${{ matrix.python }} + - name: Exercise the adapter, session-only installer and quiet wrapper + working-directory: examples/coding-agents/hook-to-otlp + env: + PYTHONDONTWRITEBYTECODE: '1' + GIT_CONFIG_NOSYSTEM: '1' + GIT_CONFIG_GLOBAL: /dev/null + run: python -m unittest tests.test_augment_adapter tests.test_augment_hooks_config -v diff --git a/examples/coding-agents/augment-code/futureagi-hook.sh b/examples/coding-agents/augment-code/futureagi-hook.sh new file mode 100755 index 000000000..f8976c5bf --- /dev/null +++ b/examples/coding-agents/augment-code/futureagi-hook.sh @@ -0,0 +1,23 @@ +#!/bin/sh +# Auggie hook command for Future AGI. +# +# Augment documents a hook command as the path to a script with a .sh +# extension, which Auggie runs with the event JSON on stdin. The settings +# therefore name this script, and the guard that other coding-agent pages put +# in the hook command lives here: +# - the emitter runs in the canonical guarded subshell, so a missing emit.py, +# a missing python3 or a crash still exits 0; +# - stdout goes to /dev/null: Auggie adds plain-text SessionStart output to the +# agent's context and reads a Stop {"decision": "block"} as "keep working", +# and this hook has nothing to tell the agent; +# - stderr goes to /dev/null, so no Python error text reaches Auggie's logs; +# - -B keeps __pycache__ out of the install folder. +# It uses no external commands, so it works with an empty PATH too. +case "$0" in + */*) HERE="${0%/*}" ;; + *) HERE=. ;; +esac +EMIT="$HERE/emit.py" +[ -f "$EMIT" ] || EMIT="$HERE/../hook-to-otlp/emit.py" +(python3 -B "$EMIT" augment 2>/dev/null || true) >/dev/null +exit 0 diff --git a/examples/coding-agents/augment-code/install.sh b/examples/coding-agents/augment-code/install.sh new file mode 100755 index 000000000..4bfa1337f --- /dev/null +++ b/examples/coding-agents/augment-code/install.sh @@ -0,0 +1,106 @@ +#!/usr/bin/env bash +# Install session-only Future AGI hooks for Auggie CLI 0.36.0 on macOS. +# The template registers SessionStart, Stop and SessionEnd, not tool hooks. +# +# ./install.sh hooks for every Auggie session (~/.augment/settings.json) +# ./install.sh --project REPO hooks for one repository only (REPO/.augment/settings.local.json) +# +# Copies emit.py, the Augment adapter and the futureagi-hook.sh wrapper into +# ~/.augment/fi-hook-to-otlp/. Then writes the hooks file if it does not exist. +# An existing settings file is never modified: the script prints the "hooks" +# entries to merge instead. No metadata flags are set, so Auggie does not add +# user context or conversation data to the hook input. +# +# With --project, the workspace file holds this machine's home path, so it is +# also added to the repository's local exclude list (.git/info/exclude, which +# is never committed) unless git already ignores it. No tracked file such as +# .gitignore is changed. +set -euo pipefail + +usage() { echo "usage: $0 [--project REPO]" >&2; exit 2; } + +HERE="$(cd "$(dirname "$0")" && pwd)" +EMITTER="$HERE/../hook-to-otlp" +DEST="$HOME/.augment/fi-hook-to-otlp" +SETTINGS="$HOME/.augment/settings.json" +REPO="" +case "${1:-}" in + "") [[ $# -eq 0 ]] || usage ;; + --project) + [[ $# -eq 2 && -d "$2" ]] || usage + REPO="$(cd "$2" && pwd)" + SETTINGS="$REPO/.augment/settings.local.json" ;; + *) usage ;; +esac + +# Keep /.augment/settings.local.json out of commits (see the header). +ignore_workspace_settings() { + local repo="$1" rel=".augment/settings.local.json" pattern="**/.augment/settings.local.json" exclude + if ! command -v git >/dev/null 2>&1 || ! git -C "$repo" rev-parse --is-inside-work-tree >/dev/null 2>&1; then + echo "note: $repo is not a git work tree; keep $rel out of version control" + return 0 + fi + if git -C "$repo" check-ignore -q -- "$rel"; then + echo "ignored: $rel (already ignored by git)" + return 0 + fi + exclude="$(cd "$repo" && git rev-parse --git-path info/exclude)" + case "$exclude" in /*) ;; *) exclude="$repo/$exclude" ;; esac + mkdir -p "$(dirname "$exclude")" + if [[ -s "$exclude" && -n "$(tail -c 1 "$exclude")" ]]; then echo >> "$exclude"; fi + printf '%s\n' "# Future AGI Auggie hooks: personal settings with this machine's home path" "$pattern" >> "$exclude" + if git -C "$repo" check-ignore -q -- "$rel"; then + echo "ignored: $rel (added to $exclude)" + else + echo "warning: git still tracks $repo/$rel; do not commit it, it contains your home path" >&2 + fi +} + +# settings.json with the wrapper path filled in. Built with json.dump, so any +# character in the home directory gives valid JSON. Auggie 0.36.0 splits a +# command containing a literal space, or runs one containing |&;><$` through +# bash, so only those paths need single quotes. Other characters (including +# Unicode and parentheses) go straight to spawn: quotes would become part of +# the filename instead of being removed. +# Built before anything is copied, so a path that cannot be registered leaves +# no partial install behind. Keep the heredoc outside command substitution: +# macOS Bash 3.2 can misparse quotes and backticks inside a nested heredoc. +render_hooks() { + python3 - "$HERE/settings.json" "$DEST/futureagi-hook.sh" <<'PY' +import json, re, sys +template, wrapper = sys.argv[1], sys.argv[2] +if "'" in wrapper: + sys.exit(f"cannot register a hook path that contains a single quote: {wrapper}") +if re.search(r"[ |&;><$`]", wrapper): + wrapper = f"'{wrapper}'" +with open(template, encoding="utf-8") as f: + settings = json.load(f) +for groups in settings["hooks"].values(): + for group in groups: + for hook in group["hooks"]: + hook["command"] = wrapper +print(json.dumps(settings, indent=2)) +PY +} +HOOKS="$(render_hooks)" + +mkdir -p "$DEST/adapters" +cp "$EMITTER/emit.py" "$DEST/emit.py" +cp "$EMITTER/adapters/__init__.py" "$EMITTER/adapters/base.py" "$EMITTER/adapters/augment.py" "$DEST/adapters/" +cp "$HERE/futureagi-hook.sh" "$DEST/futureagi-hook.sh" +chmod +x "$DEST/futureagi-hook.sh" +echo "emitter: $DEST" + +if [[ -e "$SETTINGS" ]]; then + echo "kept existing $SETTINGS; merge these entries into its \"hooks\" object:" + echo "$HOOKS" +else + mkdir -p "$(dirname "$SETTINGS")" + echo "$HOOKS" > "$SETTINGS" + echo "hooks: $SETTINGS" +fi +if [[ -n "$REPO" ]]; then ignore_workspace_settings "$REPO"; fi + +echo +echo "Credentials: put FI_API_KEY, FI_SECRET_KEY and FI_PROJECT_NAME in" +echo "~/.config/fi-hook-to-otlp/env (chmod 600), or export them before starting auggie." diff --git a/examples/coding-agents/augment-code/run_e2e.sh b/examples/coding-agents/augment-code/run_e2e.sh new file mode 100755 index 000000000..fa70688a1 --- /dev/null +++ b/examples/coding-agents/augment-code/run_e2e.sh @@ -0,0 +1,39 @@ +#!/usr/bin/env bash +# Drive the real emitter, through the same futureagi-hook.sh wrapper Auggie +# runs, with Auggie hook payloads into a Future AGI collector. +# +# FI_API_KEY=... FI_SECRET_KEY=... FI_BASE_URL=http://localhost:14338 \ +# FI_PROJECT_NAME=augment-e2e ./run_e2e.sh [fixture.jsonl] +# +# Default input is the documented-shape session in +# ../hook-to-otlp/tests/fixtures/augment/session.jsonl (it also turns on every +# opt-in metadata block, to show they are dropped). Each line runs the wrapper +# as its own process, exactly as Auggie runs a hook command. Every run gets a +# fresh conversation id, printed at the end with its trace id. +set -euo pipefail + +HERE="$(cd "$(dirname "$0")" && pwd)" +EMITTER="$HERE/../hook-to-otlp" +FIXTURE="${1:-$EMITTER/tests/fixtures/augment/session.jsonl}" +: "${FI_API_KEY:?set FI_API_KEY}" "${FI_SECRET_KEY:?set FI_SECRET_KEY}" +export FI_PROJECT_NAME="${FI_PROJECT_NAME:-augment-e2e}" + +RUN_ID="augment-e2e-$(date +%Y%m%d%H%M%S)-$$" +python3 - "$FIXTURE" "$RUN_ID" <<'PY' | while IFS= read -r payload; do +import json, sys +for line in open(sys.argv[1], encoding="utf-8"): + if line.strip(): + payload = json.loads(line)["payload"] + payload["conversation_id"] = sys.argv[2] + print(json.dumps(payload)) +PY + rc=0 + printf '%s' "$payload" | "$HERE/futureagi-hook.sh" || rc=$? + event="$(printf '%s' "$payload" | python3 -c 'import json,sys; print(json.load(sys.stdin)["hook_event_name"])')" + echo "$event exit=$rc" + sleep "${REPLAY_SLEEP:-0.3}" +done + +TRACE_ID="$(cd "$EMITTER" && python3 -B -c 'import sys, emit; print(emit.trace_id("augment", sys.argv[1]))' "$RUN_ID")" +echo "conversation_id=$RUN_ID" +echo "trace_id=$TRACE_ID" diff --git a/examples/coding-agents/augment-code/settings.json b/examples/coding-agents/augment-code/settings.json new file mode 100644 index 000000000..b397c1146 --- /dev/null +++ b/examples/coding-agents/augment-code/settings.json @@ -0,0 +1,37 @@ +{ + "hooks": { + "SessionStart": [ + { + "hooks": [ + { + "type": "command", + "command": "/Users/you/.augment/fi-hook-to-otlp/futureagi-hook.sh", + "timeout": 5000 + } + ] + } + ], + "Stop": [ + { + "hooks": [ + { + "type": "command", + "command": "/Users/you/.augment/fi-hook-to-otlp/futureagi-hook.sh", + "timeout": 5000 + } + ] + } + ], + "SessionEnd": [ + { + "hooks": [ + { + "type": "command", + "command": "/Users/you/.augment/fi-hook-to-otlp/futureagi-hook.sh", + "timeout": 5000 + } + ] + } + ] + } +} diff --git a/examples/coding-agents/hook-to-otlp/adapters/augment.py b/examples/coding-agents/hook-to-otlp/adapters/augment.py new file mode 100644 index 000000000..f0b423655 --- /dev/null +++ b/examples/coding-agents/hook-to-otlp/adapters/augment.py @@ -0,0 +1,111 @@ +"""Augment Code (Auggie CLI) hooks -> normalized span events. + +Payload shapes follow https://docs.augmentcode.com/cli/hooks (read +2026-10-14): every event carries ``hook_event_name``, ``conversation_id`` +(the session) and ``workspace_roots``. Tool events carry ``tool_name``, +``tool_input`` and ``is_mcp_tool``; ``PostToolUse`` adds ``tool_output``, +``tool_error`` and ``file_changes``. ``Stop`` carries ``agent_stop_cause``. +Auggie sends no turn id, no tool call id, no tool timing, no model id and +no token counts, so this adapter does not produce turn spans and tool spans +have no measured duration. + +Mapped events: + + SessionStart -> opens the session (the root span is sent with the first + child span; an empty session exports nothing) + PostToolUse -> tool span (ERROR when tool_error is set) + tool_input / tool_output / tool_error = content + Stop -> event span "Agent stop" (ERROR when the cause is + "error"); the last cause is also kept on the session + SessionEnd -> session end + +``PreToolUse`` is deliberately not registered or mapped: it is the hook that +can block a tool, and tracing never takes part in approving or blocking. As a +result tool spans have no measured duration. + +``Stop`` carries ``agent_stop_cause``: ``end_turn``, ``interrupted``, +``max_iterations``, ``error`` (documented) and ``empty_completion`` (0.36.0, +undocumented). Every cause is recorded as-is; only ``error`` sets ERROR. + +Never exported, even with content capture on: ``workspace_roots``, the +``context`` object (``includeUserContext``: user email, model display name), +the ``conversation`` object (``includeConversationData``), ``user_prompt`` +(0.36.0 adds it to tool events when ``includeConversationData`` is on), +``_exchange`` (0.36.0 passes this internal object on ``Stop``), +``mcp_metadata``, and file paths and contents from ``file_changes`` (only the +count and change types). MCP tool names are ``_``, so the MCP +server name is exported as part of the tool name. + +With content capture off, a tool error exports only the fixed status message +``tool error``; the ``tool_error`` text is content. +""" +from __future__ import annotations + +from typing import Any, Dict, List + +from adapters.base import ( + END, ERROR, EVENT, INSTANT, OK, SESSION, START, TOOL, UPDATE, + SpanEvent, compact, first, +) + +APP = "augment" +DISPLAY_NAME = "Auggie" +SERVICE_NAME = "auggie-cli" + + +def _file_change_attrs(payload: Dict[str, Any]) -> Dict[str, Any]: + changes = payload.get("file_changes") + if not isinstance(changes, list): + return {} + types = sorted({str(c.get("changeType")) for c in changes if isinstance(c, dict) and c.get("changeType")}) + return compact({ + "augment.tool.file_changes.count": len(changes), + "augment.tool.file_changes.types": types, + }) + + +def parse(event: str, payload: Dict[str, Any]) -> List[SpanEvent]: + session = first(payload, "conversation_id") + if not session: + return [] # R-01: never invent a session id + sid = str(session) + + if event == "SessionStart": + return [SpanEvent(START, SESSION, sid)] + + if event == "SessionEnd": + return [SpanEvent(END, SESSION, sid)] + + if event == "PostToolUse": + tool_name = str(first(payload, "tool_name") or "tool") + error = payload.get("tool_error") + failed = error not in (None, "") + return [SpanEvent( + END, TOOL, sid, + name=tool_name, + status=ERROR if failed else OK, + status_message="tool error" if failed else None, + input=payload.get("tool_input"), + output=None if failed else payload.get("tool_output"), + error_message=error if failed else None, + attributes=compact({ + "augment.tool.name": tool_name, + "augment.tool.is_mcp": payload.get("is_mcp_tool"), + **_file_change_attrs(payload), + }), + )] + + if event == "Stop": + cause = payload.get("agent_stop_cause") + failed = cause == "error" + return [ + SpanEvent( + INSTANT, EVENT, sid, name="Agent stop", + status=ERROR if failed else OK, + status_message="agent stopped with error" if failed else None, + attributes=compact({"augment.stop.cause": cause}), + ), + SpanEvent(UPDATE, SESSION, sid, attributes=compact({"augment.stop.last_cause": cause})), + ] + + return [] diff --git a/examples/coding-agents/hook-to-otlp/tests/fixtures/augment/session.jsonl b/examples/coding-agents/hook-to-otlp/tests/fixtures/augment/session.jsonl new file mode 100644 index 000000000..8690ed8bf --- /dev/null +++ b/examples/coding-agents/hook-to-otlp/tests/fixtures/augment/session.jsonl @@ -0,0 +1,10 @@ +{"event": "SessionStart", "payload": {"hook_event_name": "SessionStart", "conversation_id": "fixture-conv-aug-0001", "workspace_roots": ["/Users/fixture/project"], "context": {"userEmail": "fixture.user@example.com", "modelName": "MODEL_LABEL_CANARY", "toolVersion": "0.36.0", "timestamp": "2026-10-14T10:30:00-08:00"}}} +{"event": "PreToolUse", "payload": {"hook_event_name": "PreToolUse", "conversation_id": "fixture-conv-aug-0001", "workspace_roots": ["/Users/fixture/project"], "tool_name": "launch-process", "tool_input": {"command": "TOOL_INPUT_MARKER_AUG ls -la"}, "is_mcp_tool": false}} +{"event": "PostToolUse", "payload": {"hook_event_name": "PostToolUse", "conversation_id": "fixture-conv-aug-0001", "workspace_roots": ["/Users/fixture/project"], "tool_name": "launch-process", "tool_input": {"command": "TOOL_INPUT_MARKER_AUG ls -la"}, "tool_output": "TOOL_OUTPUT_MARKER_AUG README.md", "is_mcp_tool": false, "context": {"userEmail": "fixture.user@example.com", "modelName": "MODEL_LABEL_CANARY", "toolVersion": "0.36.0", "timestamp": "2026-10-14T10:30:00-08:00"}, "user_prompt": "PROMPT_CANARY_AUG list the files"}} +{"event": "PostToolUse", "payload": {"hook_event_name": "PostToolUse", "conversation_id": "fixture-conv-aug-0001", "workspace_roots": ["/Users/fixture/project"], "tool_name": "view", "tool_input": {"path": "README.md"}, "tool_output": "TOOL_OUTPUT_MARKER_AUG # demo", "is_mcp_tool": false}} +{"event": "PostToolUse", "payload": {"hook_event_name": "PostToolUse", "conversation_id": "fixture-conv-aug-0001", "workspace_roots": ["/Users/fixture/project"], "tool_name": "str-replace-editor", "tool_input": {"path": "src/auth.ts", "old_str_1": "TOOL_INPUT_MARKER_AUG old", "new_str_1": "TOOL_INPUT_MARKER_AUG new"}, "tool_output": "File edited successfully", "is_mcp_tool": false, "file_changes": [{"path": "src/auth.ts", "changeType": "edit", "content": "FILE_CONTENT_CANARY new", "oldContent": "FILE_CONTENT_CANARY old"}]}} +{"event": "PostToolUse", "payload": {"hook_event_name": "PostToolUse", "conversation_id": "fixture-conv-aug-0001", "workspace_roots": ["/Users/fixture/project"], "tool_name": "search_example-server", "tool_input": {"query": "TOOL_INPUT_MARKER_AUG docs"}, "tool_error": "ERROR_MARKER_AUG permission denied: /Users/fixtureuser/project/.env", "is_mcp_tool": true, "mcp_metadata": {"timestamp": "2026-10-14T10:31:00-08:00", "mcpDecision": "yes", "mcpTotalToolsCount": 7319, "mcpExecutedToolName": "search_example-server", "mcpExecutedToolServerName": "example-server", "mcpExecutedToolServerToolsCount": 6}}} +{"event": "Stop", "payload": {"hook_event_name": "Stop", "conversation_id": "fixture-conv-aug-0001", "workspace_roots": ["/Users/fixture/project"], "agent_stop_cause": "end_turn", "context": {"userEmail": "fixture.user@example.com", "modelName": "MODEL_LABEL_CANARY", "toolVersion": "0.36.0", "timestamp": "2026-10-14T10:30:00-08:00"}, "conversation": {"userPrompt": "CONVERSATION_CANARY prompt", "agentTextResponse": "CONVERSATION_CANARY reply", "agentCodeResponse": [{"path": "src/auth.ts", "changeType": "edit", "content": "CONVERSATION_CANARY code"}]}, "_exchange": {"request_message": "EXCHANGE_CANARY prompt", "response_text": "EXCHANGE_CANARY reply"}}} +{"event": "PostToolUse", "payload": {"hook_event_name": "PostToolUse", "conversation_id": "fixture-conv-aug-0001", "workspace_roots": ["/Users/fixture/project"], "tool_name": "view", "tool_input": {"path": "src/auth.ts"}, "tool_output": "TOOL_OUTPUT_MARKER_AUG body", "is_mcp_tool": false}} +{"event": "Stop", "payload": {"hook_event_name": "Stop", "conversation_id": "fixture-conv-aug-0001", "workspace_roots": ["/Users/fixture/project"], "agent_stop_cause": "error"}} +{"event": "SessionEnd", "payload": {"hook_event_name": "SessionEnd", "conversation_id": "fixture-conv-aug-0001", "workspace_roots": ["/Users/fixture/project"], "context": {"userEmail": "fixture.user@example.com", "modelName": "MODEL_LABEL_CANARY", "toolVersion": "0.36.0", "timestamp": "2026-10-14T10:30:00-08:00"}}} diff --git a/examples/coding-agents/hook-to-otlp/tests/test_augment_adapter.py b/examples/coding-agents/hook-to-otlp/tests/test_augment_adapter.py new file mode 100644 index 000000000..9019a52cb --- /dev/null +++ b/examples/coding-agents/hook-to-otlp/tests/test_augment_adapter.py @@ -0,0 +1,163 @@ +"""Auggie CLI adapter contract tests against payloads shaped as https://docs.augmentcode.com/cli/hooks documents them. + +The fixture turns on every opt-in metadata block Auggie offers +(``context``, ``conversation``, ``mcp_metadata``, ``file_changes``) and adds +the two undocumented fields the 0.36.0 bundle can put in the hook input +(``user_prompt`` on tool events, ``_exchange`` on ``Stop``), to prove the +adapter drops them. The MCP tool follows Augment's ``_`` +naming, so the server name is (by design) part of the exported tool name. +""" +from __future__ import annotations + +import json +import tempfile +import unittest + +from tests.helpers import FIXTURES, attrs, by_name, config, latest, load_jsonl, replay + +import emit +from adapters import augment +from adapters.base import ERROR, OK, SESSION, TURN + +SESSION_FIXTURE = FIXTURES / "augment" / "session.jsonl" +SID = "fixture-conv-aug-0001" +MARKERS = ("TOOL_INPUT_MARKER_AUG", "TOOL_OUTPUT_MARKER_AUG", "ERROR_MARKER_AUG") +# Never exported, even with content capture on (R-03, R-04, section 12). +NEVER = ("fixture.user@example.com", "MODEL_LABEL_CANARY", "CONVERSATION_CANARY", + "FILE_CONTENT_CANARY", "PROMPT_CANARY_AUG", "EXCHANGE_CANARY", "/Users/fixture/project") +# tool_error text in the fixture: a home path with a user name. +ERROR_USER = "fixtureuser" +MCP_TOTAL_TOOLS = 7319 # mcp_metadata.mcpTotalToolsCount in the fixture + + +def all_attribute_values(spans): + for span in spans: + for item in span.get("attributes", []): + yield item["key"], next(iter(item["value"].values())) + + +class AugmentAdapterTest(unittest.TestCase): + def setUp(self): + self.tmp = tempfile.TemporaryDirectory() + self.records = load_jsonl(SESSION_FIXTURE) + + def tearDown(self): + self.tmp.cleanup() + + def spans(self, capture=False): + extra = {"FI_HOOK_CAPTURE_CONTENT": "1"} if capture else {} + return replay(augment, config("augment", self.tmp.name, **extra), self.records) + + def test_session_only_recipe_exports_stops_without_content_or_tools(self): + # Filter the synthetic fixture to the three shipped lifecycle hooks. + # This exercises the supported recipe without claiming a live tool run. + records = [r for r in self.records if r["event"] in ("SessionStart", "Stop", "SessionEnd")] + for capture in ("0", "1"): + with tempfile.TemporaryDirectory() as state: + cfg = config("augment", state, FI_HOOK_CAPTURE_CONTENT=capture) + spans = replay(augment, cfg, records) + root_id = emit.span_id("augment", SID, SESSION, "") + root = latest(spans, root_id) + self.assertEqual(root["name"], "Auggie session") + self.assertEqual(attrs(root)["session.id"], SID) + self.assertEqual(attrs(root)["augment.stop.last_cause"], "error") + self.assertEqual({s["traceId"] for s in spans}, {emit.trace_id("augment", SID)}) + children = [s for s in spans if s.get("parentSpanId") == root_id] + self.assertEqual([s["name"] for s in children], ["Agent stop", "Agent stop"]) + self.assertEqual([attrs(s)["augment.stop.cause"] for s in children], ["end_turn", "error"]) + for marker in MARKERS + NEVER + (ERROR_USER, "/Users/"): + self.assertNotIn(marker, json.dumps(spans), marker) + + def test_session_without_a_stop_exports_nothing(self): + records = [r for r in self.records if r["event"] in ("SessionStart", "SessionEnd")] + self.assertEqual(replay(augment, config("augment", self.tmp.name), records), []) + + def test_one_trace_keyed_by_conversation_id(self): + spans = self.spans() + self.assertEqual({s["traceId"] for s in spans}, {emit.trace_id("augment", SID)}) + root_id = emit.span_id("augment", SID, SESSION, "") + root = latest(spans, root_id) + self.assertEqual(root["name"], "Auggie session") + self.assertEqual(attrs(root)["fi.span.kind"], "AGENT") + self.assertEqual(attrs(root)["augment.stop.last_cause"], "error") + children = sorted(s["name"] for s in spans if s.get("parentSpanId") == root_id) + self.assertEqual(children, ["Agent stop", "Agent stop", "launch-process", + "search_example-server", "str-replace-editor", "view", "view"]) + self.assertFalse([s for s in spans if attrs(s).get("coding_agent.scope") == TURN]) + + def test_tools_are_unique_spans_with_status(self): + spans = self.spans() + views = by_name(spans, "view") + self.assertEqual(len({s["spanId"] for s in views}), 2) + a = attrs(views[0]) + self.assertEqual((a["fi.span.kind"], a["gen_ai.tool.name"], a["augment.tool.is_mcp"]), + ("TOOL", "view", False)) + self.assertNotIn("gen_ai.tool.call.id", a) # Auggie sends no tool call id + mcp = by_name(spans, "search_example-server")[0] + self.assertEqual(mcp["status"], {"code": 2, "message": "tool error"}) + self.assertTrue(attrs(mcp)["augment.tool.is_mcp"]) + edit = attrs(by_name(spans, "str-replace-editor")[0]) + self.assertEqual(edit["augment.tool.file_changes.count"], "1") + self.assertEqual(edit["augment.tool.file_changes.types"], {"values": [{"stringValue": "edit"}]}) + + def test_stop_cause_and_error(self): + stops = by_name(self.spans(), "Agent stop") + self.assertEqual([attrs(s)["augment.stop.cause"] for s in stops], ["end_turn", "error"]) + self.assertEqual(stops[0]["status"]["code"], 1) + self.assertEqual(stops[1]["status"], {"code": 2, "message": "agent stopped with error"}) + + def test_every_0_36_0_stop_cause_is_recorded_as_is(self): + # 0.36.0 enum: interrupted, end_turn, max_iterations, empty_completion (undocumented), error. + for cause in ("interrupted", "end_turn", "max_iterations", "empty_completion", "error"): + stop, update = augment.parse("Stop", {"hook_event_name": "Stop", "conversation_id": SID, + "agent_stop_cause": cause}) + self.assertEqual(stop.attributes, {"augment.stop.cause": cause}) + self.assertEqual(stop.status, ERROR if cause == "error" else OK, cause) + self.assertEqual(update.attributes, {"augment.stop.last_cause": cause}) + + def test_pre_tool_use_is_not_mapped(self): + self.assertEqual(augment.parse("PreToolUse", self.records[1]["payload"]), []) + + def test_default_export_has_no_content_or_pii(self): + spans = self.spans() + encoded = json.dumps(spans) + for marker in MARKERS + NEVER + (ERROR_USER, "/Users/"): + self.assertNotIn(marker, encoded, marker) + + def test_error_text_with_a_path_and_user_name_is_content(self): + mcp = by_name(self.spans(), "search_example-server")[0] + self.assertEqual(mcp["status"]["message"], "tool error") # fixed text, never the error + self.assertNotIn("exception.message", attrs(mcp)) + captured = attrs(by_name(self.spans(capture=True), "search_example-server")[0]) + self.assertIn("ERROR_MARKER_AUG permission denied: /Users//project/.env", captured["exception.message"]) + self.assertNotIn(ERROR_USER, json.dumps(captured)) + + def test_mcp_server_is_only_in_the_tool_name(self): + # Augment names MCP tools _: the server name goes out in the tool name, + # nothing else from mcp_metadata does. + for capture in (False, True): + spans = self.spans(capture=capture) + mcp = attrs(by_name(spans, "search_example-server")[0]) + self.assertEqual(mcp["gen_ai.tool.name"], "search_example-server") + for key, value in all_attribute_values(spans): + self.assertNotIn("mcp_metadata", key) + self.assertNotIn(str(MCP_TOTAL_TOOLS), str(value), key) + if key not in ("gen_ai.tool.name", "augment.tool.name", "input.value"): + self.assertNotIn("example-server", str(value), key) + + def test_capture_content_opt_in_still_drops_metadata_blocks(self): + spans = self.spans(capture=True) + encoded = json.dumps(spans) + for marker in MARKERS: + self.assertIn(marker, encoded, marker) + for marker in NEVER: + self.assertNotIn(marker, encoded, marker) + mcp = attrs(by_name(spans, "search_example-server")[0]) + self.assertIn("ERROR_MARKER_AUG", mcp["exception.message"]) + + def test_missing_conversation_id_is_dropped(self): + self.assertEqual(augment.parse("PostToolUse", {"tool_name": "view"}), []) + + +if __name__ == "__main__": + unittest.main() diff --git a/examples/coding-agents/hook-to-otlp/tests/test_augment_hooks_config.py b/examples/coding-agents/hook-to-otlp/tests/test_augment_hooks_config.py new file mode 100644 index 000000000..660d0b8ca --- /dev/null +++ b/examples/coding-agents/hook-to-otlp/tests/test_augment_hooks_config.py @@ -0,0 +1,301 @@ +"""The shipped Auggie hooks must never block or steer Auggie, with or without the emitter. + +How Auggie 0.36.0 runs a hook command on macOS/Linux (read from the @augmentcode/auggie bundle, +functions dao/QIt/cao/E7n and vao; Augment documents the command as "path to the script"): + +- A command with no shell metacharacter is executed directly (spawn, shell: false). If it contains + a space it is first split into words, honouring single and double quotes. +- A command that starts with ``~`` or contains one of ``| & ; > < $ ` `` runs as ``bash -c ``. +- The event JSON is written to the process's stdin. Exit code 2 blocks only on PreToolUse; any + other non-zero exit, or a command that cannot be started, is logged and the session continues. + Exit 0 stdout is parsed as JSON (a Stop ``{"decision": "block"}`` keeps the agent working); + stdout that is not JSON is shown to the user, or on SessionStart added to the agent's context. + So the hook must print nothing. + +Augment documents the command as the path to a ``.sh`` script, so the shipped settings name a +script and the guard lives in it: futureagi-hook.sh runs +``(python3 -B emit.py augment 2>/dev/null || true) >/dev/null`` and exits 0. (0.36.0 would also +run a guarded one-line command through ``bash -c``, see auggie_argv, but that form is not +documented, so it is not used.) These tests run every installed command the way Auggie does. +Shell-compatible command strings are also run through ``sh -c`` with the payload on stdin +and as a trailing heredoc, with the emitter installed, with emit.py missing and with python3 +missing. Literal Unicode and parentheses-only paths exercise Auggie's direct-spawn branch, +not an extra shell that Auggie does not use. If the whole install folder is deleted, Auggie +cannot start the wrapper; 0.36.0 logs that as a failed hook and continues (none of the +registered events can block). +""" +from __future__ import annotations + +import json +import os +import re +import shutil +import subprocess +import tempfile +import unittest +from pathlib import Path + +from tests.helpers import Receiver, attrs + +EXAMPLE = Path(__file__).resolve().parents[2] / "augment-code" +TEMPLATE_COMMAND = "/Users/you/.augment/fi-hook-to-otlp/futureagi-hook.sh" +OBSERVE_EVENTS = ["SessionStart", "Stop", "SessionEnd"] +SHELLS = [sh for sh in ("/bin/sh", "/bin/bash", "/bin/zsh", "/bin/dash") if os.path.exists(sh)] +WORKSPACE_FILE = ".augment/settings.local.json" +# These names trigger neither Auggie's word splitter nor its shell dispatcher. +DIRECT_SPAWN_HOMES = ["José", "name(test)"] +# Also retain space, JSON/sed-special and shell-metacharacter coverage. +HOMES = ["home", "my home", "odd &#\"\\$HOME`x`", *DIRECT_SPAWN_HOMES] + +_META = re.compile(r"[|&;><$`]") +_WORDS = re.compile(r'"([^"]*(?:\\.[^"]*)*)"|\'([^\']*(?:\\.[^\']*)*)\'|(\S+)') + + +def auggie_argv(command, args=()): + """Port of Auggie 0.36.0's POSIX command resolution (dao, QIt, E7n, cao).""" + if command.startswith("~") or (not args and _META.search(command)): + return ["bash", "-c", f"{command} {' '.join(args)}" if args else command] + if not args and " " in command: + words = [next(g for g in m.groups() if g is not None) for m in _WORDS.finditer(command)] + return words or [command] + return [command, *args] + + +def commands(settings): + return [(event, hook) for event, groups in settings["hooks"].items() + for group in groups for hook in group["hooks"]] + + +def payload(event, sid, cwd): + body = {"hook_event_name": event, "conversation_id": sid, "workspace_roots": [str(cwd)]} + if event == "PostToolUse": + body.update(tool_name="view", tool_input={"path": "README.md"}, + tool_output="it's $HOME `id` \"quoted\" OUTPUT_MARK", is_mcp_tool=False) + if event == "Stop": + body["agent_stop_cause"] = "end_turn" + return body + + +def run_hook(command, body, env, cwd, transport, shell="/bin/sh"): + text = json.dumps(body, indent=2) # Auggie serializes the event with indent 2 + if transport == "auggie": + argv = auggie_argv(command) + return subprocess.run(argv, cwd=cwd, input=text, capture_output=True, text=True, env=env, + timeout=30) + if transport == "stdin": + return subprocess.run([shell, "-c", command], cwd=cwd, input=text, capture_output=True, + text=True, env=env, timeout=30) + script = f"{command} <<'AUGGIE_HOOK_EOF'\n{text}\nAUGGIE_HOOK_EOF" + return subprocess.run([shell, "-c", script], cwd=cwd, stdin=subprocess.DEVNULL, + capture_output=True, text=True, env=env, timeout=30) + + +def shells_without_python(tmp): + """A PATH with sh and bash but no python3.""" + bin_dir = Path(tmp, "no-python-bin") + bin_dir.mkdir() + for name in ("sh", "bash"): + os.symlink(f"/bin/{name}", bin_dir / name) + return str(bin_dir) + + +class AugmentHooksConfigTest(unittest.TestCase): + def base_env(self, home, **extra): + env = {"PATH": os.environ.get("PATH", "/usr/bin:/bin"), "HOME": str(home)} + env.update(extra) + return env + + def run_install(self, home, *args): + return subprocess.run([str(EXAMPLE / "install.sh"), *args], capture_output=True, text=True, + env=self.base_env(home, GIT_CONFIG_NOSYSTEM="1")) + + def install(self, tmp, home_name, *args): + home = Path(tmp, home_name) + home.mkdir() + result = self.run_install(home, *args) + self.assertEqual(result.returncode, 0, result.stderr) + return home + + def git(self, home, repo, *args): + return subprocess.run(["git", "-C", str(repo), "-c", "user.name=t", "-c", "user.email=t@example.com", + *args], capture_output=True, text=True, + env=self.base_env(home, GIT_CONFIG_NOSYSTEM="1")) + + def test_template_registers_session_hooks_only(self): + settings = json.loads((EXAMPLE / "settings.json").read_text()) + self.assertEqual(list(settings["hooks"]), OBSERVE_EVENTS) # no PreToolUse or PostToolUse + for event, hook in commands(settings): + self.assertEqual(hook, {"type": "command", "command": TEMPLATE_COMMAND, "timeout": 5000}, event) + self.assertNotIn("metadata", json.dumps(settings)) # no includeUserContext / ConversationData + + def test_installed_commands_send_the_payload_and_print_nothing(self): + with tempfile.TemporaryDirectory() as tmp: + project = Path(tmp, "project") + project.mkdir() + for home_index, home_name in enumerate(HOMES): + home = self.install(tmp, home_name) + wrapper = home / ".augment" / "fi-hook-to-otlp" / "futureagi-hook.sh" + settings = json.loads((home / ".augment" / "settings.json").read_text()) + runs = [("auggie", "/bin/sh")] + if home_name not in DIRECT_SPAWN_HOMES: + runs += [("stdin", "/bin/sh"), ("heredoc", "/bin/sh")] + if home_name == "home": + runs += [(t, sh) for sh in SHELLS for t in ("stdin", "heredoc")] + for transport, shell in runs: + label = f"{home_name!r} {transport} {shell}" + for _event, hook in commands(settings): + argv = auggie_argv(hook["command"]) + if home_name in DIRECT_SPAWN_HOMES: + self.assertEqual(hook["command"], str(wrapper), label) + if argv[0] == "bash": + self.assertEqual(argv, ["bash", "-c", f"'{wrapper}'"], label) + else: + self.assertEqual(argv, [str(wrapper)], label) + rx = Receiver() + try: + sid = f"cfg-{home_index}-{transport}-{Path(shell).name}" + env = self.base_env(home, FI_API_KEY="k", FI_SECRET_KEY="s", FI_HOOK_SYNC="1", + FI_HOOK_CAPTURE_CONTENT="1", + FI_OTLP_ENDPOINT=rx.url + "/tracer/v1/traces", + FI_HOOK_STATE_DIR=str(Path(tmp, f"state-{sid}"))) + for event, hook in commands(settings): + result = run_hook(hook["command"], payload(event, sid, project), env, project, + transport, shell) + self.assertEqual((result.returncode, result.stdout, result.stderr), (0, "", ""), + f"{label} {event}") + session_spans = rx.spans() + self.assertEqual({s["name"] for s in session_spans}, + {"Agent stop", "Auggie session"}, label) + self.assertEqual({attrs(s)["session.id"] for s in session_spans}, {sid}, label) + stop = [s for s in session_spans if s["name"] == "Agent stop"][-1] + self.assertEqual(attrs(stop)["augment.stop.cause"], "end_turn", label) + # Keep the synthetic transport/escaping regression for the adapter's + # tool parser without registering it in the customer configuration. + tool_sid = sid + "-synthetic-tool" + result = run_hook(hook["command"], + payload("PostToolUse", tool_sid, project), env, project, + transport, shell) + self.assertEqual((result.returncode, result.stdout, result.stderr), (0, "", ""), label) + spans = rx.spans() + finally: + rx.close() + view = [s for s in spans if s["name"] == "view"][-1] + self.assertEqual(attrs(view)["session.id"], tool_sid, label) + # The heredoc is quoted: no expansion of $HOME, backticks or quotes on the way in. + self.assertEqual(attrs(view)["output.value"], payload("PostToolUse", sid, project)["tool_output"], + label) + self.assertEqual(list(home.rglob("__pycache__")), [], "-B keeps bytecode out") + + def test_missing_emitter_or_python_exits_0_with_no_output(self): + with tempfile.TemporaryDirectory() as tmp: + home = self.install(tmp, "home") + (home / ".augment" / "fi-hook-to-otlp" / "emit.py").unlink() + settings = json.loads((home / ".augment" / "settings.json").read_text()) + no_python = shells_without_python(tmp) + for path_label, path in (("emit.py missing", None), ("python3 missing", no_python)): + env = self.base_env(home, **({"PATH": path} if path else {})) + for shell in SHELLS: + for transport in ("auggie", "stdin", "heredoc"): + if transport == "auggie" and shell != SHELLS[0]: + continue + for event, hook in commands(settings): + result = run_hook(hook["command"], payload(event, "cfg-missing", tmp), env, tmp, + transport, shell) + self.assertEqual((result.returncode, result.stdout, result.stderr), (0, "", ""), + f"{path_label} {shell} {transport} {event}") + + def test_project_install_writes_only_the_workspace_file(self): + with tempfile.TemporaryDirectory() as tmp: + repo = Path(tmp, "repo") + repo.mkdir() + home = Path(tmp, "home") + home.mkdir() + result = self.run_install(home, "--project", str(repo)) + self.assertEqual(result.returncode, 0, result.stderr) + local = repo / WORKSPACE_FILE + self.assertTrue(local.exists()) + self.assertFalse((home / ".augment" / "settings.json").exists()) + wrapper = home / ".augment" / "fi-hook-to-otlp" / "futureagi-hook.sh" + for _event, hook in commands(json.loads(local.read_text())): + self.assertEqual(auggie_argv(hook["command"]), [str(wrapper)]) + self.assertIn("is not a git work tree", result.stdout) # nothing to ignore it with + + @unittest.skipUnless(shutil.which("git"), "git not installed") + def test_project_install_keeps_the_workspace_file_out_of_git(self): + """The workspace file holds this machine's home path, so `git add -A` must not pick it up. + + The installer adds it to the repository's local exclude list (never committed) and changes + no tracked file: from a subfolder, from the root, on a re-run and in a linked worktree. + """ + pattern = "**/" + WORKSPACE_FILE + with tempfile.TemporaryDirectory() as tmp: + home = Path(tmp, "home") + home.mkdir() + repo = Path(tmp, "repo") + (repo / "sub").mkdir(parents=True) + self.assertEqual(self.git(home, repo, "init", "-q").returncode, 0) + for target in (repo / "sub", repo, repo): + result = self.run_install(home, "--project", str(target)) + self.assertEqual(result.returncode, 0, result.stderr) + self.assertEqual(self.git(home, target, "check-ignore", "-q", "--", WORKSPACE_FILE).returncode, + 0, f"{target}: {result.stdout}") + self.assertIn(str(home), (target / WORKSPACE_FILE).read_text()) # why it must stay local + exclude = repo / ".git" / "info" / "exclude" + self.assertEqual(exclude.read_text().count(pattern), 1) + self.assertFalse((repo / ".gitignore").exists()) + self.assertEqual(self.git(home, repo, "status", "--porcelain", "--untracked-files=all").stdout, "") + + # A linked worktree shares the main repository's exclude list. + self.assertEqual(self.git(home, repo, "commit", "-q", "--allow-empty", "-m", "init").returncode, 0) + worktree = Path(tmp, "worktree") + self.assertEqual(self.git(home, repo, "worktree", "add", "-q", str(worktree)).returncode, 0) + exclude.write_text("") + result = self.run_install(home, "--project", str(worktree)) + self.assertEqual(result.returncode, 0, result.stderr) + self.assertEqual(self.git(home, worktree, "check-ignore", "-q", "--", WORKSPACE_FILE).returncode, 0) + self.assertEqual(exclude.read_text().count(pattern), 1) + self.assertEqual(self.git(home, worktree, "status", "--porcelain", "--untracked-files=all").stdout, "") + + @unittest.skipUnless(shutil.which("git"), "git not installed") + def test_project_install_leaves_an_existing_ignore_rule_alone(self): + with tempfile.TemporaryDirectory() as tmp: + home = Path(tmp, "home") + home.mkdir() + repo = Path(tmp, "repo") + repo.mkdir() + self.assertEqual(self.git(home, repo, "init", "-q").returncode, 0) + (repo / ".gitignore").write_text(WORKSPACE_FILE + "\n") # what Auggie itself adds + exclude = repo / ".git" / "info" / "exclude" + before = exclude.read_text() + result = self.run_install(home, "--project", str(repo)) + self.assertEqual(result.returncode, 0, result.stderr) + self.assertIn("already ignored", result.stdout) + self.assertEqual(exclude.read_text(), before) + self.assertEqual((repo / ".gitignore").read_text(), WORKSPACE_FILE + "\n") + + def test_unregistrable_home_stops_before_copying(self): + """A home path with a single quote cannot be registered; nothing is installed.""" + with tempfile.TemporaryDirectory() as tmp: + home = Path(tmp, "it's home") + home.mkdir() + result = self.run_install(home) + self.assertEqual(result.returncode, 1) + self.assertIn("single quote", result.stderr) + self.assertEqual(list(home.iterdir()), []) + + def test_existing_settings_file_is_never_modified(self): + with tempfile.TemporaryDirectory() as tmp: + home = Path(tmp, "home") + (home / ".augment").mkdir(parents=True) + existing = home / ".augment" / "settings.json" + existing.write_text('{"model": "keep-me"}\n') + result = subprocess.run([str(EXAMPLE / "install.sh")], capture_output=True, text=True, + env=self.base_env(home)) + self.assertEqual(result.returncode, 0, result.stderr) + self.assertEqual(existing.read_text(), '{"model": "keep-me"}\n') + self.assertIn("merge these entries", result.stdout) + self.assertIn(str(home / ".augment" / "fi-hook-to-otlp" / "futureagi-hook.sh"), result.stdout) + + +if __name__ == "__main__": + unittest.main() diff --git a/scripts/augment-code-page.test.mjs b/scripts/augment-code-page.test.mjs new file mode 100644 index 000000000..3a44c34e4 --- /dev/null +++ b/scripts/augment-code-page.test.mjs @@ -0,0 +1,57 @@ +import test from 'node:test'; +import assert from 'node:assert/strict'; +import fs from 'node:fs'; +import { integrations } from '../src/lib/integrations.mjs'; + +const read = file => fs.readFileSync(new URL(`../${file}`, import.meta.url), 'utf8'); +const page = read('src/pages/docs/integrations/coding-agents/augment-code.mdx'); +const template = JSON.parse(read('examples/coding-agents/augment-code/settings.json')); + +test('Auggie guide and shipped hooks agree on the session-only macOS scope', () => { + const sample = page.match(/```json\n([\s\S]*?)\n```/)?.[1]; + assert.ok(sample, 'Show the generated session hook configuration'); + assert.deepEqual(JSON.parse(sample), template); + assert.deepEqual(Object.keys(template.hooks), ['SessionStart', 'Stop', 'SessionEnd']); + for (const groups of Object.values(template.hooks)) { + for (const group of groups) { + assert.equal(group.metadata, undefined); + for (const hook of group.hooks) { + assert.equal(hook.type, 'command'); + assert.equal(hook.timeout, 5000); + assert.equal(hook.command, '/Users/you/.augment/fi-hook-to-otlp/futureagi-hook.sh'); + } + } + } + assert.match(page, /Auggie CLI 0\.36\.0 on macOS/); + assert.match(page, /npm install --global @augmentcode\/auggie@0\.36\.0/); + assert.match(page, /Node\.js 20 or later/); + assert.match(page, /new CLI sessions only/); + assert.match(page, /Tool tracing, resumed conversations[^\n]+outside its scope/); + assert.match(page, /remove its Future AGI `PostToolUse` entry; retain unrelated hooks/); + assert.match(page, /There are no turn spans or tool spans in this configuration/); + assert.match(page, /session with no stop event exports nothing/); +}); + +test('Auggie guide preserves the installer, credential, privacy and removal contract', () => { + for (const term of [ + 'install.sh --project /path/to/your/repo', + 'FI_API_KEY=', 'FI_SECRET_KEY=', 'FI_PROJECT_NAME=auggie-sessions', + 'umask 077', 'chmod 600', 'FI_HOOK_CAPTURE_CONTENT=0', + '$FI_BASE_URL/tracer/v1/traces', 'FI_HOOK_DISABLED=1', + '`context`', '`conversation`', '`user_prompt`', '`_exchange`', '`workspace_roots`', + 'includeUserContext', 'includeConversationData', + 'before deleting', 'single quote', 'remove it from tracking', + ]) assert.ok(page.includes(term), term); + assert.doesNotMatch(page, /verification status|verified live|documented.shape only|no usage left|read 2026-|fi_verify|run_e2e\.sh/i); + assert.doesNotMatch(page, /well under a second|more tool spans|with tool calls/); +}); + +test('Auggie is discoverable as a CLI lifecycle integration, not tool tracing', () => { + const entry = integrations.find(item => item.id === 'augment-code'); + assert.ok(entry); + assert.equal(entry.href, '/docs/integrations/coding-agents/augment-code'); + assert.equal(entry.category, 'coding'); + assert.equal(entry.method, 'Hook-to-OTLP'); + assert.match(entry.summary, /new macOS CLI sessions/); + assert.doesNotMatch(entry.summary, /tool calls|tool spans/); +}); diff --git a/scripts/integrations.test.mjs b/scripts/integrations.test.mjs index 30ff909ed..3c81efbff 100644 --- a/scripts/integrations.test.mjs +++ b/scripts/integrations.test.mjs @@ -1,3 +1,4 @@ +import './augment-code-page.test.mjs'; import './ollama-java.test.mjs'; import './azure-openai-java.test.mjs'; import './langsmith-page.test.mjs'; diff --git a/src/lib/integrations.mjs b/src/lib/integrations.mjs index df0f390a2..e4a45312e 100644 --- a/src/lib/integrations.mjs +++ b/src/lib/integrations.mjs @@ -57,6 +57,7 @@ export const integrations = [ { id: 'gradio', name: 'Gradio', href: '/docs/integrations/traceai/gradio', category: 'frameworks', summary: 'Trace synchronous chat callbacks through their model client.', method: 'OpenAI client', logo: 'generic-framework' }, { id: 'z-ai', name: 'Z.ai', href: '/docs/integrations/providers/z-ai', category: 'providers', summary: 'Trace Python chat completions on the general-platform endpoint.', method: 'OpenAI client', logo: 'generic-model' }, { id: 'cursor', name: 'Cursor IDE', href: '/docs/integrations/coding-agents/cursor', category: 'coding', summary: 'Trace macOS IDE agent sessions through observation hooks.', method: 'Hook-to-OTLP', logo: 'generic-framework' }, + { id: 'augment-code', name: 'Augment Code (Auggie CLI)', href: '/docs/integrations/coding-agents/augment-code', category: 'coding', summary: 'Trace new macOS CLI sessions and stop causes with lifecycle hooks.', method: 'Hook-to-OTLP', logo: 'generic-framework', aliases: ['Auggie'] }, { id: 'langsmith', name: 'LangSmith', href: '/docs/integrations/langsmith', category: 'frameworks', summary: 'Forward supported LangSmith SDK traces over OTLP.', method: 'Native OTLP', logo: 'generic-framework' }, {"id": "mlflow", "name": "MLflow", "href": "/docs/integrations/mlflow", "category": "frameworks", "summary": "Export current MLflow traces with OTLP/HTTP.", "method": "Native OTLP", "logo": "generic-framework"}, { id: 'openai', name: 'OpenAI', href: '/docs/integrations/traceai/openai', category: 'providers', summary: 'Instrument OpenAI client calls in your application.', method: 'traceAI SDK', logo: 'openai' }, diff --git a/src/pages/docs/integrations/coding-agents/augment-code.mdx b/src/pages/docs/integrations/coding-agents/augment-code.mdx new file mode 100644 index 000000000..21fb12846 --- /dev/null +++ b/src/pages/docs/integrations/coding-agents/augment-code.mdx @@ -0,0 +1,108 @@ +--- +title: "Augment Code (Auggie CLI) session tracing" +description: "Send Auggie CLI session events from macOS to Future AGI with the shared hook-to-OTLP emitter, without exporting prompts or responses." +--- + +Send Auggie CLI session starts, stops, and ends to Future AGI using Augment's [hooks](https://docs.augmentcode.com/cli/hooks) and the shared [hook-to-OTLP emitter](/docs/integrations/coding-agents/hook-to-otlp). Each conversation appears as an **Auggie session** trace with **Agent stop** child spans. + +## Prerequisites + +- **Auggie CLI 0.36.0 on macOS**, Node.js 20 or later, and an Augment account signed in with `auggie login`. +- **Python 3.9 or later** on the `PATH` Auggie uses. The emitter needs no Python packages. +- Your [Future AGI API and secret keys](/docs/admin-settings/api-keys). + +This recipe covers new CLI sessions only. Tool tracing, resumed conversations (`--continue` or `--resume`), Augment IDE extensions, Linux, and Windows are outside its scope. It does not export model calls, token usage, cost, prompts, or responses. + +## 1. Install Auggie and the hook + +Use the version covered by this recipe: + +```bash +npm install --global @augmentcode/auggie@0.36.0 +auggie login +``` + +Clone the maintained examples and run the installer for your repository: + +```bash +git clone --depth 1 https://github.com/future-agi/docs.git fi-docs +fi-docs/examples/coding-agents/augment-code/install.sh --project /path/to/your/repo +``` + +The installer places the emitter and wrapper in `~/.augment/fi-hook-to-otlp/` and writes `/.augment/settings.local.json`. If that settings file already exists, it leaves it unchanged and prints the entries to merge into its `hooks` object. These workspace settings apply only to the CLI. + +The generated configuration uses your home directory in place of `/Users/you`: + +```json +{ + "hooks": { + "SessionStart": [{ "hooks": [{ "type": "command", "command": "/Users/you/.augment/fi-hook-to-otlp/futureagi-hook.sh", "timeout": 5000 }] }], + "Stop": [{ "hooks": [{ "type": "command", "command": "/Users/you/.augment/fi-hook-to-otlp/futureagi-hook.sh", "timeout": 5000 }] }], + "SessionEnd": [{ "hooks": [{ "type": "command", "command": "/Users/you/.augment/fi-hook-to-otlp/futureagi-hook.sh", "timeout": 5000 }] }] + } +} +``` + +The wrapper prints nothing and exits successfully even if Python or the emitter is unavailable. It does not inject context or prevent the agent from stopping. Timeouts are in milliseconds; the emitter exports in a background process. + +Keep the workspace settings out of version control: they contain your absolute home path. The installer adds a local Git exclusion unless the file is already ignored; it does not edit `.gitignore`. If Git already tracks the file, remove it from tracking before adding personal settings. Home paths containing a single quote are not supported by the installer. + +To trace new sessions across all repositories instead, run the installer without `--project`. That writes `~/.augment/settings.json`, which Augment IDE extensions also read. For CLI-only, repository-scoped tracing, use the project installation above and remove any Future AGI entries from the user-level file. If you used an earlier configuration, also remove its Future AGI `PostToolUse` entry; retain unrelated hooks. + +## 2. Add your Future AGI keys + +Create the emitter's credential file with owner-only permissions. If you already use it for another coding agent, update the existing file instead of replacing it. + +```bash +mkdir -p ~/.config/fi-hook-to-otlp +(umask 077; cat > ~/.config/fi-hook-to-otlp/env <<'EOF' +FI_API_KEY=your-futureagi-api-key +FI_SECRET_KEY=your-futureagi-secret-key +FI_PROJECT_NAME=auggie-sessions +FI_HOOK_CAPTURE_CONTENT=0 +EOF +) +chmod 600 ~/.config/fi-hook-to-otlp/env +``` + +Auggie's environment variables take precedence over this file. For self-hosted Future AGI, also set `FI_BASE_URL`; the emitter sends traces to `$FI_BASE_URL/tracer/v1/traces`. See the [shared configuration reference](/docs/integrations/coding-agents/hook-to-otlp#configuration) for other settings. + +## 3. Run a new session + +From the repository where you installed the hooks, start a new conversation: + +```bash +auggie --print "Explain what a README is in one sentence. Do not use tools." +``` + +Open **Observe** in Future AGI and select **auggie-sessions**. Open the **Auggie session** trace to see its **Agent stop** child and stop cause. Each subsequent `Stop` event in the same interactive conversation adds another child; it is not a model-request span. + +## What is captured + +| Hook | Result in Future AGI | +| --- | --- | +| `SessionStart` | Starts an **Auggie session**, keyed by `conversation_id` and exposed as `session.id`. The root is exported with the first stop span. | +| `Stop` | Adds an **Agent stop** child with `augment.stop.cause`, and updates `augment.stop.last_cause` on the root. Only the cause `error` marks the child `ERROR`, with the fixed message `agent stopped with error`. | +| `SessionEnd` | Ends the session span. A session with no stop event exports nothing. | + +There are no turn spans or tool spans in this configuration. Stop events mark when the agent stops responding, not the duration of a model call. + +## Privacy + +The session configuration exports conversation identifiers, lifecycle timing, stop causes, and status. It does not export prompts, responses, user email, model display names, or workspace paths. The adapter ignores `context`, `conversation`, `user_prompt`, `_exchange`, and `workspace_roots`, including when those fields appear in a hook payload. + +Leave `includeUserContext` and `includeConversationData` off: enabling them adds sensitive data to the local hook input without adding session telemetry. Keep `FI_HOOK_CAPTURE_CONTENT=0`; session events do not need content capture. See the [shared privacy reference](/docs/integrations/coding-agents/hook-to-otlp#privacy). + +## Troubleshooting + +**No trace appears.** + +1. Confirm Auggie is signed in, the settings file contains the three hook entries, and a response has ended. An empty session sends no trace. +2. Check that `~/.augment/fi-hook-to-otlp/futureagi-hook.sh` is executable and that `python3` resolves in the shell used to launch Auggie. +3. Set `FI_HOOK_LOG_FILE=/tmp/fi-hook.log` in the credential file and start another session. `http=401` or `http=403` indicates an authentication problem; `error=` indicates an export failure. If no line appears after a stop, check hook registration, credentials, and that `FI_HOOK_DISABLED` is not `1`. + +**Other repositories still produce traces.** Remove the Future AGI entries from `~/.augment/settings.json` and retain only the project-scoped entries. + +## Uninstall + +Remove the three Future AGI hook entries from the workspace or user settings before deleting `~/.augment/fi-hook-to-otlp/`. To pause all integrations using the shared emitter configuration, set `FI_HOOK_DISABLED=1` in its credential file instead.