Hugs

 phase (gate or agent)            cliqd                       CliqHub                    people
 ─────────────────────            ─────                       ───────                    ──────
 ctx.ask(spec) ──── open ───────▶ stores the Hug ── create ──▶ resolves channels ──────▶ notified on their
                                                              stores the Hug             channels (email, Slack,
                                                                                         in-app…) → Hug page
          ◀──── next (events) ─── persists events ◀─ deliver ── validates & stores ◀───── Submit response
 policy decides: wait / done / failed                          the response, files

inputs:
  - name: reviewers
    type: channel
    label: Reviewers

phases:
  - name: draft
    agent: claude-code
    prompt: Write the release notes for this sprint into notes.md

  - name: approve
    type: gate
    agent: hug
    depends_on: [draft]
    route_targets: [draft]          # adds "Send back to draft"
    max_iterations: 3               # at most 3 rounds of review (default 3)
    review:
      reviewers:
        - { policy: any, channels: ["{{inputs.reviewers}}"] }
      message: Check the release notes in notes.md before they go out.
      artifacts: [notes.md]         # attached to the review (first round)
      timeout: 2h                   # the Hug expires after 2 hours (default 30m)
      remind_every: 30m             # remind people who haven't answered
      inputs:
        - { name: note, type: textarea, label: What should change?, required: false }

  - name: publish
    agent: exec
    depends_on: [approve]
    commands:
      - run: echo "Publishing notes.md"

- name: human-review
  type: gate
  agent: hug
  depends_on: [planner]
  review:
    reviewers:
      - { policy: any, channels: ["{{inputs.reviewers}}"] }
    artifacts: [plan.md]
    inputs:
      - name: guest_list
        type: file
        label: Guest list
        help: A CSV with a header row; the first column is each guest's name
        accept: [.csv, text/csv]
        max_mb: 1
        required: true

- name: invitations
  agent: exec
  depends_on: [human-review]
  commands:
    - name: get-guest-list
      run: cliq hug files human-review guest_list guests/

{
  "files": [
    {
      "file": "ann-guests.csv",
      "artifact_id": "3f6c2a8e-…",
      "name": "guests.csv",
      "size": 128,
      "content_type": "text/csv",
      "sha256": "9b1d…",
      "phase": "human-review",
      "round": 1,
      "hug_id": "c41e…",
      "input": "guest_list",
      "responder": { "user_id": "…", "name": "ann" },
      "decision": "approve",
      "response_seq": 1,
      "received_at": "2026-10-27T10:00:00Z",
      "current": true
    }
  ]
}

cliq hug files human-review guest_list guests/                    # latest round, everyone
cliq hug files human-review guest_list guests/ --responder ann    # only Ann's (name or user id)
cliq hug files human-review guest_list all/ --round all           # every round
cliq hug files human-review guest_list r1/ --round 1              # round 1 only
cliq hug files human-review guest_list v/ --include-replaced      # also files from answers people later changed
cliq hug files human-review guest_list out/ --run quiet-amber-heron   # after a run, from the workspace

name,email
Ada Lovelace,[email protected]
Grace Hopper,[email protected]
Alan Turing,[email protected]
Katherine Johnson,[email protected]

mkdir party && cd party
cliq init
cliq assemble @cliq/hug-example
cliq run -i child=Maya -i theme=pirates -i reviewers=me

guests/<you>-guests.csv          # the uploaded file, named after who sent it
guests/files.json                # who sent it, in which round, with which decision
guests.txt                       # Ada Lovelace, Alan Turing, Grace Hopper, Katherine Johnson
invitations/Ada_Lovelace.txt     # "Dear Ada Lovelace, You are invited to a pirates party for Maya!"
invitations/Alan_Turing.txt
invitations/Grace_Hopper.txt
invitations/Katherine_Johnson.txt
shopping-list.md                 # Guests: 4 — cupcakes 6, party bags 4, balloons 8

inputs:
  - { name: asked, type: channel, label: Who to ask, required: true }

phases:
  - name: ask
    agent: hello-asker
    hug:
      channels: ["{{inputs.asked}}"]
      timeout: 2h
      remind_every: 30m

import { StandardAgent } from '@getcliqio/cliq-sdk';

class HelloAsker extends StandardAgent {
    constructor() { super('hello-asker'); }

    async on_invoke(ctx) {
        const answer = await ctx.ask({
            title: 'Hello from hello-ask',
            prompt: 'Who should we greet? Attach a file if you like.',
            requested_inputs: [
                { name: 'name', type: 'text', label: 'Name', max_length: 80 },
                { name: 'attachment', type: 'file', label: 'A file (optional)', required: false },
            ],
        });
        const { name, attachment } = answer.values;
        if (!attachment) return { text: `Hello, ${name}!` };

        // A file is a reference; read it through cliqd wherever it is stored.
        let bytes = 0;
        for await (const chunk of await ctx.download(attachment)) bytes += chunk.length;
        return { text: `Hello, ${name}! Thanks for ${attachment.name} (${bytes} bytes).` };
    }
}

new HelloAsker().start();

import { groups } from '@getcliqio/cliq-sdk';

// Inside on_invoke(ctx):
const answer = await ctx.ask({
    title: 'Release 4.2 go / no-go',
    prompt: 'Engineering and product both need to approve.',
    channels: ['eng-leads', 'product'],
    expires_in_min: 24 * 60,
    reminders: { every_min: 120 },
    requested_inputs: [
        { name: 'decision', type: 'enum', choices: [{ value: 'go' }, { value: 'no-go' }] },
        { name: 'notes', type: 'text', multiline: true, required: false },
    ],
    // Done when each group has one "go"; any "no-go" fails at once (HugRejectedError).
    policy: groups(
        [{ policy: 'any', channels: ['eng-leads'] }, { policy: 'any', channels: ['product'] }],
        { accept: (v) => v.decision === 'go', reject: (v) => v.decision === 'no-go' },
    ),
    // Don't keep the agent process alive for a day: stop now, resume when answers arrive.
    wait: 'yield',
});

// Every current guest list from the latest round of the human-review phase, everyone's.
const lists = ctx.hug_files({ phase: 'human-review', input: 'guest_list' });

for (const f of lists) {
    // Save it in the workspace (checked against size and sha256, written atomically)…
    const saved = await ctx.download(f, `guests/${f.responder.name}-${f.name}`);
    console.log(`${f.responder.name} sent ${f.name} in round ${f.round}: ${saved.path}`);
}

// …or stream it without writing a file.
const stream = await ctx.download(lists[0]);

POST /v1/realms/set_notification_rules
{ "realm_id": "5b0c3a7e-…", "event": "hug.expired", "channel_id": "9a8b7c6d-…" }