ACP Skill (Minimal)

Version: 1.0.6 | A2A Compliant

Environment (Ask Human)

Variable	Description
ACP_URL	The ACP server URL (e.g., https://xxx.trycloudflare.com)
ACP_USER	Auth username (default: admin)
ACP_PASS	Auth password (default: secret)

---

CSRF PROTECTION

CSRF protection is optional and disabled by default for development/testing convenience. When disabled, POST requests do not require a CSRF token. Enable via GLMACP_CSRF_ENABLED=true for production deployments exposed to untrusted networks.

# Check CSRF status
GET {ACP_URL}/api/csrf-token
→ {"success": true, "csrf_enabled": false, "csrf_token": null}

# If CSRF is enabled, include the token header on all POST requests:
# X-CSRF-Token: <timestamp>:<signature>

CORS (1.0.6): The server includes CORS headers and handles OPTIONS preflight requests, enabling browser-based cross-origin API consumption.

---

BOOTSTRAP (MANDATORY)

Execute on every session start / context resume:

1. GET  {ACP_URL}/api/status       → Check stop_flag and primary_agent
2. GET  {ACP_URL}/api/whoami       → Establish identity, check if you are primary agent
3. POST {ACP_URL}/api/agents/register {"agent_name": "Super Z", "capabilities": [...], "model_name": "..."}
4. GET  {ACP_URL}/api/todos        → Restore TODO state from previous session
5. POST {ACP_URL}/api/action {"action": "CHAT", "target": "Session bootstrap", "metadata": {"agent_name": "Super Z"}}
   → save activity_id from response
6. POST {ACP_URL}/api/complete {"activity_id": "<id from step 5>", "result": "Bootstrap complete"}

IMPORTANT: Step 6 is mandatory — without it the bootstrap CHAT activity stays in running[] forever, causing orphan_warning on every subsequent action.

Response Fields (1.0.5):

Endpoint	Field	Description
/api/status	stop_flag	If true, STOP immediately
/api/status	primary_agent	Name of agent that owns the context
/api/whoami	primary_agent	Who owns the context (check if it's you)
/api/action	nudge	Human guidance — only delivered to primary agent
/api/action	orphan_warning	Running tasks left uncompleted — resolve before new work

If stop_flag: true: STOP immediately, inform user, wait for POST /api/resume.

If orphan_warning in /api/action response: Complete each orphaned activity via POST /api/complete before starting new work.

---

THE PATTERN (MANDATORY)

CHECK → LOG → EXECUTE → COMPLETE
/api/status → /api/action → Tool → /api/complete
BEFORE → NOW → AFTER

MANDATORY Rules (Non-Negotiable)

1. CHECK /api/status on session start and after context recovery for stop_flag
2. LOG every action BEFORE executing via /api/action
3. LOG every shell command via /api/shell/add (except ACP API calls)
4. COMPLETE every activity when done via /api/complete

NEVER execute before logging. NEVER skip logging.

---

CORE API

Log Activity (before execution)

POST {ACP_URL}/api/action {
  "action": "READ|WRITE|EDIT|BASH|SEARCH|SKILL|API|TODO|CHAT|A2A",
  "target": "file path or resource",
  "details": "human description",
  "content_size": 0,           # Character count for token tracking (chars / 3.5 = tokens)
  "priority": "medium",        # high|medium|low
  "metadata": {"agent_name": "Super Z", "model_name": "..."}
}
→ {"activity_id": "...", "stop_flag": false, "hints": {...}, "nudge": null}

Complete Activity (after execution)

POST {ACP_URL}/api/complete {
  "activity_id": "...",
  "result": "what happened",     # Result summary (max 500 chars)
  "error": "error message",      # Error message if failed (max 200 chars) — optional
  "content_size": 0,             # Character count written (for token tracking)
  "metadata": {"file_hash": "..."}  # Additional metadata (merged with existing)
}

Combined (recommended for efficiency)

POST {ACP_URL}/api/action {
  "complete_id": "prev_id",           # Previous activity to complete
  "result": "previous result",        # Result summary for previous activity
  "error": "previous error",          # Error if previous activity failed — optional
  "complete_content_size": 0,         # Chars written in previous activity
  "complete_metadata": {"key": "..."}, # Metadata merged into previous activity
  "action": "READ",                   # New action type
  "target": "next file",              # New target
  "details": "human description",     # Description for new activity
  "content_size": 0,                  # Chars to be read in new activity
  "priority": "medium",               # Priority for new activity
  "metadata": {"agent_name": "Super Z"}  # Metadata for new activity
}

---

ACTION TYPES

Type	Use For
READ	Files, API GETs, viewing content
WRITE	Creating new files
EDIT	Modifying existing files
BASH	Terminal commands
SKILL	VLM, TTS, image-generation
API	External API calls
SEARCH	Web search, grep, find
TODO	TODO state changes
CHAT	Conversational Q&A, planning
A2A	Agent-to-agent communication

---

RESPONSE FIELDS

Check these in every /api/action response:

Field	Action
stop_flag: true	STOP immediately, inform user
nudge	Human guidance — read, adjust behavior, ack if requires_ack: true via POST /api/nudge/ack (primary agent only)
orphan_warning	Complete listed orphan tasks via POST /api/complete before proceeding
hints.modified_this_session	File was already modified — review before editing
hints.loop_detected	Same action repeated 3+ times — change approach
hints.suggestion	Actionable advice — follow it
hints.a2a.pending_count	Pending A2A messages — retrieve via GET /api/a2a/history?to=<name>

Note (1.0.5): Nudges are delivered only to the primary agent (first agent to log activity). Secondary agents always receive nudge: null. This prevents context pollution in multi-agent environments.

To check if you are primary:

GET /api/whoami
→ {"primary_agent": "Super Z", ...}

# If primary_agent matches your agent_name, you will receive nudges.
# primary_agent also appears in /api/status and /api/agents responses.

Nudge workflow:

# 1. Nudge arrives in /api/action response
→ {"nudge": {"message": "Focus on the API first", "priority": "high", "requires_ack": true}}

# 2. Read message, adjust behavior accordingly

# 3. If requires_ack: true
POST {ACP_URL}/api/nudge/ack {}
→ {"success": true}

Polling for nudges (1.0.6):

# Check if a nudge is pending without logging an action
GET {ACP_URL}/api/nudge
→ {"success": true, "nudge": {...}, "has_pending": true}

---

SHELL LOGGING (MANDATORY)

Full BASH workflow — 4 steps, every time:

# 1. Log action BEFORE running
POST {ACP_URL}/api/action {"action": "BASH", "target": "npm install", "details": "Install deps", "metadata": {"agent_name": "Super Z"}}
→ {"activity_id": "143055-d4e5f6"}

# 2. Execute the command
[run: npm install]

# 3. Log to shell history AFTER running
POST {ACP_URL}/api/shell/add {
  "command": "npm install",
  "status": "completed|error",
  "output_preview": "first 200 chars of output",
  "agent_name": "Super Z",
  "tool": "Bash"                          # Tool that executed the command — optional
}

# 4. Complete the activity
POST {ACP_URL}/api/complete {"activity_id": "143055-d4e5f6", "result": "installed 57 packages"}

Do NOT log ACP API calls themselves (curl localhost:8766/api/...) — those are monitoring overhead, not work.

---

TOKEN TRACKING

ACP estimates tokens using 3.5 characters per token. Pass content_size (character count) on actions and completions for accurate tracking.

# Reading a 35,000-char file → ~10,000 tokens logged
POST /api/action {"action": "READ", "target": "file.py", "content_size": 35000}

# Writing a 5,000-char file → ~1,428 tokens logged
POST /api/complete {"activity_id": "...", "result": "written", "content_size": 5000}

File deduplication (v1.0.3): Re-reading the same file within a session costs near-zero tokens — content is only counted once. The tokens_deduplicated: true field in the activity response confirms this. Session reset clears dedup tracking.

Per-agent token isolation (v1.0.3): The first agent to log an activity becomes the primary_agent and owns the main context window (session_tokens). All other agents are tracked separately in agent_tokens{} and do not pollute the primary agent's context window estimate.

---

OWNERSHIP MODEL (v1.0.4)

Each activity belongs to the agent that created it (metadata.agent_name). Only the owning agent may complete it.

# AgentB trying to complete AgentA's activity:
POST /api/complete {"activity_id": "abc123", "metadata": {"agent_name": "AgentB"}}
→ HTTP 403 {"success": false, "error": "activity owned by AgentA"}

In multi-agent sessions, always complete your own activities. orphan_warning only surfaces tasks owned by the requesting agent.

---

A2A MESSAGING (1.0.4)

Send Message

POST {ACP_URL}/api/a2a/send {
  "from_agent": "Super Z",
  "to_agent": "OtherAgent",
  "type": "request|response|notification",    # Default: "notification"
  "action": "do_thing",                       # Action identifier for requests — optional
  "payload": {...},                           # Message data — optional
  "priority": "normal|high|urgent",           # Default: "normal"
  "ttl": 3600,                                # Time-to-live in seconds (default: 3600)
  "reply_to": "msg_id"                        # Message ID this replies to — optional
}

Check Messages

GET {ACP_URL}/api/a2a/history?to=Super Z
GET {ACP_URL}/api/a2a/history?from=OtherAgent
GET {ACP_URL}/api/a2a/history?type=request

---

TODO SYNC

GET  {ACP_URL}/api/todos
POST {ACP_URL}/api/todos/update {"todos": [...]}
POST {ACP_URL}/api/todos/add    {"todo": {"content": "...", "priority": "high"}, "agent_name": "Super Z"}
POST {ACP_URL}/api/todos/toggle {"id": "143052-a1b2c3"}   # Toggle pending ↔ completed (1.0.6)
POST {ACP_URL}/api/todos/clear                              # Clear completed TODOs

Note: Log all TODO state changes as TODO action type via /api/action.

---

FILE MANAGER ENDPOINTS

GET /api/files/list

List directory contents.

Headers:

• X-Path: Relative path from base directory
• X-Sort-By: name | date | size
• X-Sort-Dir: asc | desc

GET /api/files/view

View file content (text files only, size limited).

Headers:

• X-Path: Relative path to file

Response:

{
  "content": "file contents...",
  "path": "path/to/file.py",
  "lines": 150,
  "tokens": 450,
  "session_tokens": 45450
}

GET /api/files/download

Download file (binary safe).

Query Parameters:

• path: Relative path to file

GET /api/files/image

Get image file.

GET /api/files/stats

Get file statistics (total files, directories, size).

POST /api/files/upload

Upload file.

Headers:

• X-Path: Destination directory
• X-Filename: File name
• Content-Type: application/octet-stream

Body: Raw binary file content

POST /api/files/save

Save edited file.

Request:

{
  "path": "path/to/file.py",
  "content": "updated content..."
}

Parameters:

Parameter	Type	Required	Description
path	string	Yes	Relative path to file
content	string	Yes	File content to save

POST /api/files/delete

Delete file or directory.

Request:

{
  "path": "path/to/delete"
}

Parameters:

Parameter	Type	Required	Description
path	string	Yes	Relative path to file or directory to delete

POST /api/files/mkdir

Create directory.

Request:

{
  "path": "parent/path",
  "name": "new_directory"
}

Parameters:

Parameter	Type	Required	Description
path	string	Yes	Parent directory path
name	string	Yes	New directory name

POST /api/files/extract

Extract archive.

Request:

{
  "path": "path/to/archive.zip"
}

Parameters:

Parameter	Type	Required	Description
path	string	Yes	Relative path to archive file

Supported formats: .zip, .tar, .tar.gz, .tgz, .tar.bz2, .tbz2, .gz, .bz2

POST /api/files/compress

Create zip archive.

Request:

{
  "path": "directory/path",
  "name": "archive.zip",
  "items": ["file1.py", "file2.py", "subdir/"]
}

Parameters:

Parameter	Type	Required	Description
path	string	Yes	Base directory path
name	string	Yes	Archive filename (should end in .zip)
items	array	Yes	List of files/directories to include

---

CONTEXT RECOVERY

Before context compression

# Save important decisions, discoveries, warnings
POST {ACP_URL}/api/notes/add {
  "category": "decision|insight|context|warning|todo",   # Default: "context"
  "content": "...",
  "importance": "normal|high"                             # Default: "normal"
}

# Export session summary to persistent file
GET {ACP_URL}/api/summary/export
→ {"filepath": "/path/to/acp_session_summary.md"}
# Share this file with the next session

On session resume

# 1. Check for acp_session_summary.md and read it if present
# 2. Restore session state
GET {ACP_URL}/api/summary    # Condensed session overview
GET {ACP_URL}/api/notes      # Saved decisions and warnings
GET {ACP_URL}/api/todos      # Restore TODO state  (also in bootstrap step 4)
GET {ACP_URL}/api/agents     # See registered agents (v1.0.4)

Note categories

Category	Use For
decision	Important choices made
insight	Key discoveries
context	User preferences, conventions
warning	Issues or problems encountered
todo	Things to do in next session

---

CONTROL ENDPOINTS

Stop / Resume

# Trigger STOP ALL — cancels all running activities
POST {ACP_URL}/api/stop {"reason": "User clicked STOP ALL"}    # reason is optional

# Clear stop flag and resume operations
POST {ACP_URL}/api/resume

Shutdown

When the human ends the session (UI button or POST /api/shutdown):

# Trigger graceful shutdown
POST {ACP_URL}/api/shutdown {
  "reason": "Session ended by user",    # Default: "Session ended by user"
  "export_summary": true                # Default: true
}

# 1. You receive a shutdown nudge in your next /api/action response
→ {"nudge": {"message": "SESSION ENDING: ...", "priority": "urgent", "requires_ack": true, "type": "shutdown"}}

# 2. Acknowledge it
POST {ACP_URL}/api/nudge/ack {}

# 3. Inform user session is ending
# 4. DO NOT attempt further ACP actions — server stops ~2s after shutdown

What /api/shutdown does: exports session summary, cancels running activities, delivers shutdown nudge, stops server after 2 seconds.

---

QUICK REFERENCE

# Bootstrap (in order)
GET  /api/status
GET  /api/whoami
POST /api/agents/register {"agent_name": "...", "capabilities": [...]}
GET  /api/todos
POST /api/action {"action": "CHAT", "target": "bootstrap", "metadata": {...}}
POST /api/complete {"activity_id": "<id from above>", "result": "Bootstrap complete"}

# Workflow (MANDATORY pattern)
POST /api/action {"action": "READ", "target": "file.py", "metadata": {...}}
# ... execute tool ...
POST /api/complete {"activity_id": "...", "result": "done"}

# Combined (efficient)
POST /api/action {"complete_id": "prev", "result": "ok", "action": "READ", "target": "next", "metadata": {...}}

# Shell commands (BASH dual-log pattern)
POST /api/action  {"action": "BASH", "target": "command", "metadata": {...}}
# ... execute command ...
POST /api/shell/add {"command": "...", "status": "completed", "output_preview": "..."}
POST /api/complete {"activity_id": "...", "result": "..."}

# Nudge
GET  /api/nudge                                    # Check pending nudge (1.0.6)
POST /api/nudge/ack {}                             # Acknowledge nudge

# Control
POST /api/stop {"reason": "..."}                   # Set stop flag
POST /api/resume                                   # Clear stop flag
POST /api/shutdown {"reason": "..."}               # Graceful session end

# Context recovery
GET  /api/summary                                  # Session overview
GET  /api/summary/export                           # Export to acp_session_summary.md
GET  /api/notes                                    # Get saved notes
POST /api/notes/add {"category": "...", "content": "...", "importance": "..."}
POST /api/notes/clear

# Utility
GET  /api/all               # Combined status + history
GET  /api/todos             # TODO list
POST /api/todos/update      # Sync TODOs
POST /api/todos/add         # Add single TODO
POST /api/todos/toggle      # Toggle TODO status (1.0.6)
POST /api/todos/clear       # Clear completed TODOs
GET  /api/stats/duration    # Performance analysis (v1.0.3)
POST /api/activity/batch    # Bulk operations (v1.0.3)
POST /api/reset             # Full session reset (v1.0.4)

# A2A
GET  /api/agents
GET  /api/agents/<name>
POST /api/agents/unregister {"agent_name": "..."}
POST /api/a2a/send
GET  /api/a2a/history?to=<name>

# File Manager
GET  /api/files/list             # List directory (X-Path, X-Sort-By, X-Sort-Dir headers)
GET  /api/files/view             # View file content (X-Path header)
GET  /api/files/download         # Download file (?path=...)
GET  /api/files/image            # Get image file
GET  /api/files/stats            # File statistics
POST /api/files/upload           # Upload file (X-Path, X-Filename, Content-Type headers)
POST /api/files/save             # Save edited file (JSON body: path, content)
POST /api/files/delete           # Delete file/directory (JSON body: path)
POST /api/files/mkdir            # Create directory (JSON body: path, name)
POST /api/files/extract          # Extract archive (JSON body: path)
POST /api/files/compress         # Create zip archive (JSON body: path, name, items)

# CSRF / CORS
GET  /api/csrf-token        # Check CSRF status / get token

---

CHECKLIST

• INVOKE THIS SKILL FIRST
• Get ACP_URL from human
• Bootstrap: status → whoami → register → todos → log → complete
• Check stop_flag in /api/status; check nudge, orphan_warning, hints in every /api/action response
• LOG before EXECUTE before COMPLETE (MANDATORY - non-negotiable)
• Include agent_name in all metadata
• Log ALL shell commands with full 4-step BASH pattern (except ACP calls)
• Log all TODO changes as TODO action type
• Pass content_size for accurate token tracking (chars / 3.5 = tokens)
• Handle ownership: only complete your own activities (HTTP 403 = someone else's)
• Save notes and export summary before context compression
• Ack shutdown nudge (type: "shutdown") and stop further ACP calls
• Use combined endpoint for efficiency: complete previous + start new in one call

---

ACP Skill 1.0.6 Minimal