Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
40 changes: 40 additions & 0 deletions .github/workflows/augment-hooks.yml
Original file line number Diff line number Diff line change
@@ -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
23 changes: 23 additions & 0 deletions examples/coding-agents/augment-code/futureagi-hook.sh
Original file line number Diff line number Diff line change
@@ -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
106 changes: 106 additions & 0 deletions examples/coding-agents/augment-code/install.sh
Original file line number Diff line number Diff line change
@@ -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 <repo>/.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."
39 changes: 39 additions & 0 deletions examples/coding-agents/augment-code/run_e2e.sh
Original file line number Diff line number Diff line change
@@ -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"
37 changes: 37 additions & 0 deletions examples/coding-agents/augment-code/settings.json
Original file line number Diff line number Diff line change
@@ -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
}
]
}
]
}
}
111 changes: 111 additions & 0 deletions examples/coding-agents/hook-to-otlp/adapters/augment.py
Original file line number Diff line number Diff line change
@@ -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 ``<tool>_<server>``, 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 []
Original file line number Diff line number Diff line change
@@ -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"}}}
Loading
Loading