nextcloud-nodered-agent/README.md

# node-red-contrib-nextcloud-agent

Node-RED nodes for **generic CLI agent** integration with Nextcloud.

Works alongside your existing [`nextcloud-nodered-ocs-api`](https://kode.hannesahlin.se/n3wk/nextcloud-nodered-ocs-api) and [`nextcloud-collabora-nodered`](https://kode.hannesahlin.se/n3wk/nextcloud-collabora-nodered) setup.

## Nodes

| Node | Category | Description |
|------|----------|-------------|
| `agent-config` | config | Shared configuration (CLI path, workspace, API endpoint) |
| `agent-exec` | agent | Execute agent CLI commands (`run`, `version`, `help`, etc.) |
| `agent-file` | agent | Read/write/list files in the agent workspace |
| `agent-process` | agent | Manage persistent agent processes |

## Quick Install

```bash
# Clone this repo
git clone https://kode.hannesahlin.se/n3wk/nextcloud-nodered-agent.git
cd nextcloud-nodered-agent

# Integrate into your existing nextcloud-node-red
NODERED_DIR=/path/to/nextcloud-node-red ./integrate-into-nodered.sh

# Rebuild and restart
cd /path/to/nextcloud-node-red
docker compose build --no-cache
docker compose up -d
```

## Bootstrap Install (VM-agnostic)

```bash
curl -fsSL https://kode.hannesahlin.se/n3wk/nextcloud-nodered-agent/raw/branch/main/bootstrap-install.sh | sudo -u ncdeploy bash
```

This auto-detects your `nextcloud-node-red` installation and patches it.

## Configuration

In Node-RED, add an **agent config** node:

- **CLI Command**: `agent` (install your agent in the Docker container)
- **Workspace Directory**: `/data/agent-workspace` (shared Docker volume)
- **API Endpoint**: `http://localhost:3000` (if agent runs in server mode)
- **Default Arguments**: `--verbose` (space-separated defaults)
- **Max Concurrent Processes**: `3`

**Important**: You must edit the Dockerfile after integration to install YOUR specific agent CLI.

## Example Flows

Import `flows/example-flows.json` for:

1. **Run Task** - Use `agent-exec` to execute a one-off task
2. **Persistent Process** - Start a process, send follow-up inputs, check status
3. **Nextcloud + Agent** - List Nextcloud files → process with agent → save back

## Docker Requirements

The integration script adds to your `nextcloud-node-red`:
- **You must add agent CLI installation** to Dockerfile (script adds placeholder)
- `agent-workspace` Docker volume mounted at `/data/agent-workspace`
- Nodes copied to `/opt/nextcloud-nodes/node-red-contrib-nextcloud-agent` and installed at container start

## Architecture

```
┌─────────────────────────────────────────────────────────────────┐
│  Nextcloud (https://cloud.example.com)                          │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │  nodered_embed app  →  iframe  →  Node-RED :1880          │  │
│  │  ┌─────────────────────────────────────────────────────┐  │  │
│  │  │  agent nodes                                        │  │  │
│  │  │  ┌──────────┐  ┌──────────┐  ┌──────────────┐      │  │  │
│  │  │  │ exec     │  │ file     │  │ process      │      │  │  │
│  │  │  └────┬─────┘  └────┬─────┘  └──────┬───────┘      │  │  │
│  │  │       │             │             │                │  │  │
│  │  │       ▼             ▼             ▼                │  │  │
│  │  │  ┌─────────────────────────────────────────┐       │  │  │
│  │  │  │  Your CLI Agent (in container)          │       │  │  │
│  │  │  │  Workspace: /data/agent-workspace       │       │  │  │
│  │  │  └─────────────────────────────────────────┘       │  │  │
│  │  └─────────────────────────────────────────────────────┘  │  │
│  └───────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────┘
```

## Usage Examples

### Execute Task with agent-exec

```javascript
// Inject node
msg.prompt = "Process all files in /data/input and generate summary";
return msg;
```

Connect to `agent-exec` with command `run`.

### Persistent Process

```javascript
// Start process
msg.action = "start";
msg.processId = "my-processor";
msg.payload = "Watch /data/input for new files and process them";
return msg;

// Send follow-up
msg.action = "send";
msg.processId = "my-processor";
msg.payload = "Also generate CSV export";
return msg;
```

### Read/Write Files in Workspace

```javascript
// Write agent output to file
msg.filePath = "results/output.txt";
msg.payload = msg.payload; // from agent-exec
msg.operation = "write";
return msg;
```

## Integration with Nextcloud Nodes

Combine with your existing `file-operations`, `ocs-api`, `collectives` nodes:

1. **Read from Nextcloud** → `file-operations` (list/download)
2. **Process with agent** → `agent-exec` (transform, analyze, generate)
3. **Write to workspace** → `agent-file` (save intermediate)
4. **Upload to Nextcloud** → `file-operations` (upload)

## Troubleshooting

| Issue | Solution |
|-------|----------|
| `agent: command not found` | Edit Dockerfile to install your agent CLI, then rebuild |
| Permission denied on workspace | Ensure `agent-workspace` volume has correct permissions |
| Process won't start | Check `docker logs nextcloud-node-red` for agent errors |
| Nodes not appearing | Restart Node-RED container; check `/data/node_modules/node-red-contrib-nextcloud-agent` |

## License

MIT — see [LICENSE](LICENSE)