fiber

Talking to the hub

Any program that can hold a socket can drive Fiber: a script, a phone app, or anything else its person writes. It starts sessions, subscribes to their event streams, and sends prompts. The hub speaks the same lines as a session's socket, one JSON object per line (What the hub speaks).

Reaching the hub

On the hub's own machine, open the local socket run/hub in Fiber home (What each part holds). No token travels there.

From another machine, either forward that socket over SSH and add it as a unix: address, or connect to the hub's port over a websocket and pair first (Remote clients).

The first exchange

Every connection opens with a hub_hello line carrying the hub's schema_version, its Fiber version and, when the build knows it, its commit (The envelope). On the port, the connection's first command is authenticate with its device token, or pair with a pairing code (Remote clients). Anything else there is answered unauthenticated and the connection closes; a wrong, used, or old pairing code is rejected pairing_failed.

Worked example

The script below opens run/hub, starts a session with start, subscribes full to it, and reads events until the turn completes. start is a hub command; subscribe is a driver command, and every answer is command_accepted or command_rejected. A command for a session the connection has not subscribed to is rejected not_subscribed. The example names the scripted provider so it runs with no vendor credential; swap in any configured model (The scripted provider).

#!/usr/bin/env python3
"""Start a session through the hub and read one turn."""
import json, socket, sys

sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
sock.connect(sys.argv[1])  # $FIBER_HOME/run/hub
stream = sock.makefile("r")

def send(obj):
    sock.sendall((json.dumps(obj) + "\n").encode())

print(json.loads(next(stream))["kind"])  # hub_hello
send({"id": "c_start", "command": "start", "args": {
    "workspace": sys.argv[2], "model": "scripted/hello.json",
    "content": [{"type": "text", "text": "Say hello."}]}})
for raw in stream:
    line = json.loads(raw)
    if line.get("kind") == "command_accepted" \
            and line["payload"].get("command_id") == "c_start":
        session = line["payload"]["result"]["session_id"]
        break
send({"id": "c_sub", "session_id": session,
      "command": "subscribe", "args": {"level": "full"}})
for raw in stream:
    line = json.loads(raw)
    print(line["kind"])
    if line.get("kind") == "turn_completed":
        break

Against a running hub the script prints one kind per line, in this order, exactly as the hub sent them: hub_hello, command_accepted, command_accepted, …, turn_completed.

The second command_accepted opens the replay: the lines up to its last_seq follow it, then the live stream runs to turn_completed.

Every line but the hub's own carries its session, with the envelope of The envelope.