working out the worker/execution interface

2026-02-08 12:55:33 -06:00
parent c62f41669d
commit a74e13fa0b
108 changed files with 21162 additions and 674 deletions
--- a/docs/actions/README.md
+++ b/docs/actions/README.md
@@ -0,0 +1,163 @@
+# Action Parameter Delivery
+
+This directory contains documentation for Attune's secure parameter passing system for actions.
+
+## Quick Links
+
+- **[Parameter Delivery Guide](./parameter-delivery.md)** - Complete guide to parameter delivery methods, formats, and best practices (568 lines)
+- **[Quick Reference](./QUICKREF-parameter-delivery.md)** - Quick decision matrix and copy-paste templates (365 lines)
+
+## Overview
+
+Attune provides three methods for delivering parameters to actions, with **stdin + JSON as the secure default** (as of 2025-02-05):
+
+### Delivery Methods
+
+| Method | Security | Use Case |
+|--------|----------|----------|
+| **stdin** (default) | ✅ High | Credentials, structured data, most actions |
+| **env** (explicit) | ⚠️ Low | Simple non-sensitive shell scripts only |
+| **file** | ✅ High | Large payloads, complex configurations |
+
+### Serialization Formats
+
+| Format | Best For | Example |
+|--------|----------|---------|
+| **json** (default) | Python/Node.js, structured data | `{"key": "value"}` |
+| **dotenv** | Shell scripts, simple key-value | `KEY='value'` |
+| **yaml** | Human-readable configs | `key: value` |
+
+## Security Warning
+
+⚠️ **Environment variables are visible in process listings** (`ps aux`, `/proc/<pid>/environ`)
+
+**Never use `env` delivery for sensitive parameters** like passwords, API keys, or tokens.
+
+## Quick Start
+
+### Secure Action (Default - No Configuration Needed)
+
+```yaml
+# action.yaml
+name: my_action
+ref: mypack.my_action
+runner_type: python
+entry_point: my_action.py
+# Uses default stdin + json (no need to specify)
+
+parameters:
+  type: object
+  properties:
+    api_key:
+      type: string
+      secret: true
+```
+
+```python
+# my_action.py
+import sys, json
+
+# Read from stdin (the default)
+content = sys.stdin.read()
+params = json.loads(content.split('---ATTUNE_PARAMS_END---')[0])
+api_key = params['api_key']  # Secure - not in process list!
+```
+
+### Simple Shell Script (Non-Sensitive - Explicit env)
+
+```yaml
+# action.yaml
+name: simple_script
+ref: mypack.simple_script
+runner_type: shell
+entry_point: simple.sh
+# Explicitly use env for non-sensitive data
+parameter_delivery: env
+parameter_format: dotenv
+```
+
+```bash
+# simple.sh
+MESSAGE="${ATTUNE_ACTION_MESSAGE:-Hello}"
+echo "$MESSAGE"
+```
+
+## Key Features
+
+- ✅ **Secure by default** - stdin prevents process listing exposure
+- ✅ **Type preservation** - JSON format maintains data types
+- ✅ **Automatic cleanup** - Temporary files auto-deleted
+- ✅ **Flexible formats** - Choose JSON, YAML, or dotenv
+- ✅ **Explicit opt-in** - Only use env when you really need it
+
+## Environment Variables
+
+All actions receive these metadata variables:
+
+- `ATTUNE_PARAMETER_DELIVERY` - Method used (stdin/env/file)
+- `ATTUNE_PARAMETER_FORMAT` - Format used (json/dotenv/yaml)
+- `ATTUNE_PARAMETER_FILE` - File path (file delivery only)
+- `ATTUNE_ACTION_<KEY>` - Individual parameters (env delivery only)
+
+## Breaking Change Notice
+
+**As of 2025-02-05**, the default parameter delivery changed from `env` to `stdin` for security.
+
+Actions that need environment variable delivery must **explicitly opt-in** by setting:
+
+```yaml
+parameter_delivery: env
+parameter_format: dotenv
+```
+
+This is allowed because Attune is in pre-production with no users or deployments (per AGENTS.md policy).
+
+## Best Practices
+
+1. ✅ **Use default stdin + json** for most actions
+2. ✅ **Mark sensitive parameters** with `secret: true`
+3. ✅ **Only use env explicitly** for simple, non-sensitive shell scripts
+4. ✅ **Test credentials don't appear** in `ps aux` output
+5. ✅ **Never log sensitive parameters**
+
+## Example Actions
+
+See the core pack for examples:
+
+- `packs/core/actions/http_request.yaml` - Uses stdin + json (handles API tokens)
+- `packs/core/actions/echo.yaml` - Uses env + dotenv (no secrets)
+- `packs/core/actions/sleep.yaml` - Uses env + dotenv (no secrets)
+
+## Documentation Structure
+
+```
+docs/actions/
+├── README.md                          # This file - Overview and quick links
+├── parameter-delivery.md              # Complete guide (568 lines)
+│   ├── Security concerns
+│   ├── Detailed method descriptions
+│   ├── Format specifications
+│   ├── Configuration syntax
+│   ├── Best practices
+│   ├── Migration guide
+│   └── Complete examples
+└── QUICKREF-parameter-delivery.md     # Quick reference (365 lines)
+    ├── TL;DR
+    ├── Decision matrix
+    ├── Copy-paste templates
+    ├── Common patterns
+    └── Testing tips
+```
+
+## Getting Help
+
+1. **Quick decisions**: See [QUICKREF-parameter-delivery.md](./QUICKREF-parameter-delivery.md)
+2. **Detailed guide**: See [parameter-delivery.md](./parameter-delivery.md)
+3. **Check delivery method**: Look at `ATTUNE_PARAMETER_DELIVERY` env var
+4. **Test security**: Run `ps aux | grep attune-worker` to verify secrets aren't visible
+
+## Summary
+
+**Default**: `stdin` + `json` - Secure, structured, type-preserving parameter passing.
+
+**Remember**: stdin is the default. Environment variables require explicit opt-in! 🔒