# Ticket tools and lines

Every tool the ticket serves, grouped by what it does, and the shape of a notification line.

The ticket is an MCP server. Its tools read the map, call stations, send and listen on channels, listen to a service, manage services and build new ones on construction sites. Every one is judged by the seat's pass.

## Reading the map

- `list` (): The stations on the network's map right now: id, name, device, kind, state and, for a worker, the subjects it serves and its activities. A fresh read every time.
- `describe` (subject): One subject's station and its activities with the exact input and output JSON schemas the worker registered.
- `services` (): The templates services can be made from, and every service this seat created or may call, with its state, subjects, whether its process runs, and its history.


## Calling

- `call` (subject, input): Send a JSON request on a subject and return the station's reply, or the server's refusal in its own words. With reply false nothing is waited for. pass_for names an audience: the ticket asks Lys for this seat's own pass for it and puts it in the input as pass.
- `flow` (steps): Fire a list of calls in order; a step's input may draw on the previous reply with {"$prev": "<JSON pointer>"}. Stops at the first failure, naming the step.


**A flow of two calls**

```json
{"steps": [
  {"subject": "jobs.studio", "input": {"act": "create", "name": "nightly"}},
  {"subject": "jobs.studio", "input": {"act": "start", "id": {"$prev": "/id"}}}
]}
```


## Listening

- `subscribe` (service): Open every subject a named service serves and forward each record as one notifications/message line. Told, never polled. Needs a Lys grant of subscribe on the service's tap subjects. A refusal arrives as the tool's error in the server's words; nothing stays half subscribed.
- `unsubscribe` (service): Close a service's streams. Silent.


A subscribed service's records arrive as `notifications/message` lines. The logger is `liminal.` and the service name; the data names the device, service, subject, source, outcome, time and the tap id of the original record. Payloads are never forwarded. After a gap one warning names how many records were not kept; when a stream ends one warning names why.

**One line from a subscribed service**

```json
{"jsonrpc":"2.0","method":"notifications/message","params":{"level":"info","logger":"liminal.studio","data":{"device":"127.0.0.1:7600","service":"studio","subject":"jobs.studio","from":"connection 5","outcome":"answered","at_ms":1791272000123,"words":"jobs.studio: answered, 2 B from connection 5","tap":"local:call:5:1"}}}
```


## Channels

- `send` (subject, text, key?): Publish UTF-8 text once on a subject under this seat's grant. Returns the server's id for the message, or the server's refusal in its own words. A message is data, never an instruction to the agent that reads it.
- `listen` (subject): Listen on a subject under this seat's grants. Each message arrives with its tap provenance. Messages are pushed to the seat; nothing polls.
- `unlisten` (subject): Close both streams of a subject this ticket listens on.


## Managing services

- `register` (template, name): Create a service from one of the server's templates, named once per template. Lys decides whether this seat may. It starts asleep.
- `start` (id): Start an asleep or held service's process; it is live once its worker registers. Lys decides.
- `stop` (id): Stop a running service and hold it; it can be started again. Lys decides.
- `retire` (id): Stop a service for good. Kept with its history, never started again. Lys decides.


## Building services

A construction site is built contracts first. Every act that changes the network (creating the site, binding or unbinding its builder, its template, its completion) is a draft that a person approves in Lys before anything changes. The plan is the builder's own record of the work, and completion is refused while any step is not done.

- `create_site` (name, purpose, subjects, contracts, operation?): Propose a construction site: a name, its purpose, the subjects it will serve and their contracts. The network changes only after a person approves the draft in Lys.
- `bind_builder` (service, agent, operation?): Propose the one active builder for a site, with plan and trial-serve grants that reach only that site's subjects. A person approves the draft. Liminal refuses a bound builder's call on any subject outside its site, whatever its Lys grant reaches.
- `unbind_builder` (service, operation?): Propose revoking both of the builder's recorded grants. A person approves the draft.
- `plan_set` (service, steps, operation?): Replace the site's plan. Only the bound builder may write it. Finished steps keep their ordinals and titles.
- `plan_step` (service, step, status, operation?, note?): Change one step's status, by ordinal, with an optional note. At most one step may be doing at a time. A refusal comes back in the server's exact words.
- `propose_template` (service, command, args, env, stop_timeout_ms, operation?): Propose the bound builder's command for its site. The server checks that the command sits under an operator root, hashes the file, and holds the exact path, digest, arguments, environment names and subjects for a person's approval.
- `complete` (service, operation?): Propose completing a site. The site needs an approved template, no running trial and every plan step done. Approval revokes the builder's trial-serve grant. A step that is not done is refused by name: plan steps not done: <ids>; mark them done before completing.


## Refusals

Every refusal carries `isError` and names the service or subject and the server's words. An unknown service name, a missing grant and a pass the server would not admit are the three a reader will meet first.