Concorde

Appearance

@shutter-network/concorde/signals ​

The HTTP routes this component serves: 4 on the Agent server.

Every path is relative. Each one is printed as the plugin declares it, under whatever prefix the component's constructor registers that plugin at. This page states no mount point, because the constructor is where the mount point is decided.

Generated from what the route plugins in src/signals/routes.ts declare, which is what a running Gateway serves at GET /openapi.json. Never edited by hand.

Agent server ​

The Agent server has no authentication of any kind. Everything below is reachable by the agent, and therefore by an injected prompt (ADR-0003). Nothing on it names a credential.

GET /runs ​

Read prior Runs, newest first

Every Run this Gateway has recorded, newest first, in every Session. Reads are not scoped by Session or by User, so there is no such parameter to pass, and the Session your own Run is in changes nothing about what you get back. signalId narrows to the Runs one Signal produced. limit defaults to 50 and is capped at 200. A larger value is refused with a 400 rather than quietly reduced. There is no cursor and no offset, so the records past the cap are reachable only by narrowing. An unknown query parameter is a 400, not a filter that did nothing and a request answered with everything.

Tagged Runs.

Query parameters

  • limit integer, optional, 1 to 200, default 50
  • signalId string, optional, matching ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$

Responses

200 application/json

The Runs that matched, newest first by startedAt, which puts a Run that has not started yet at the front, since it has no start time to order by.

  • runs array of object, required

    • id string, required

    • signalId string, required

      The Signal whose Signal Handler wrote this Prompt. Several Runs can carry the same one, a Handler being free to answer with several Prompts.

    • session string or null, required

      The Session this Run happened in, as a plain name that refers to nothing. A Handler that asked for a fresh Session gets run_<this Run's id>. It is null only on Runs recorded before the Worker named every Session.

    • prompt string, required

    • state string, required, one of "pending", "running", "done", "failed"

      How the Run ended, or that it has not. One-way, and there is no timed_out, because the framework imposes no timeouts of any kind.

    • error string or null, required

    • startedAt string or null, required

    • endedAt string or null, required

400 application/json

The limit is out of range or not an integer, signalId is not a uuid, or a parameter this route does not take was written.

  • statusCode integer, required
  • error string, required
  • message string, required

GET /runs/{id} ​

Read one Run by id

One Run, in whatever Session it executed. Reads are not scoped by Session or by User, so there is no such parameter to pass, and the Session your own Run is in changes nothing about what you get back. This route takes no query parameters at all. An unknown query parameter is a 400, not a filter that did nothing and a request answered with everything.

Tagged Runs.

Path parameters

  • id string, required, matching ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$

Responses

200 application/json

The Run.

  • id string, required

  • signalId string, required

    The Signal whose Signal Handler wrote this Prompt. Several Runs can carry the same one, a Handler being free to answer with several Prompts.

  • session string or null, required

    The Session this Run happened in, as a plain name that refers to nothing. A Handler that asked for a fresh Session gets run_<this Run's id>. It is null only on Runs recorded before the Worker named every Session.

  • prompt string, required

  • state string, required, one of "pending", "running", "done", "failed"

    How the Run ended, or that it has not. One-way, and there is no timed_out, because the framework imposes no timeouts of any kind.

  • error string or null, required

  • startedAt string or null, required

  • endedAt string or null, required

400 application/json

The id in the path is not a uuid, or a query parameter was written.

  • statusCode integer, required
  • error string, required
  • message string, required

404 application/json

No Run has that id.

  • statusCode integer, required
  • error string, required
  • message string, required

GET /signals ​

Read prior Signals, newest first

Every Signal this Gateway has, in arrival order reversed, whichever Producer emitted it. Reads are not scoped by Session or by User, so there is no such parameter to pass, and the Session your own Run is in changes nothing about what you get back. limit defaults to 50 and is capped at 200. A larger value is refused with a 400 rather than quietly reduced. There is no cursor and no offset, so the records past the cap are reachable only by narrowing. An unknown query parameter is a 400, not a filter that did nothing and a request answered with everything.

Tagged Signals.

Query parameters

  • limit integer, optional, 1 to 200, default 50
  • kind string, optional

Responses

200 application/json

The Signals that matched, newest first.

  • signals array of object, required

    • id string, required

    • kind string, required

    • payload any JSON, required

      Arbitrary JSON, exactly as the Producer wrote it. The Signal Worker never interprets a payload, so what a given kind carries is the Operator's convention and their Signal Handler is where it is stated.

    • emittedAt string, required

      When the Signal was written, ISO 8601, since JSON has no date. It is also the queue's order: the oldest pending Signal is claimed first.

    • state string, required, one of "pending", "processing", "done", "failed"

      How far the Signal got. One-way: nothing returns to pending, and a failed Signal is never re-run, so error is the whole of what happened to it.

    • error string or null, required

400 application/json

The limit is out of range or not an integer, or a parameter this route does not take was written.

  • statusCode integer, required
  • error string, required
  • message string, required

GET /signals/{id} ​

Read one Signal by id

One Signal, whatever produced it and whatever Session the reader is in. Reads are not scoped by Session or by User, so there is no such parameter to pass, and the Session your own Run is in changes nothing about what you get back. This route takes no query parameters at all. An unknown query parameter is a 400, not a filter that did nothing and a request answered with everything.

Tagged Signals.

Path parameters

  • id string, required, matching ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$

Responses

200 application/json

The Signal.

  • id string, required

  • kind string, required

  • payload any JSON, required

    Arbitrary JSON, exactly as the Producer wrote it. The Signal Worker never interprets a payload, so what a given kind carries is the Operator's convention and their Signal Handler is where it is stated.

  • emittedAt string, required

    When the Signal was written, ISO 8601, since JSON has no date. It is also the queue's order: the oldest pending Signal is claimed first.

  • state string, required, one of "pending", "processing", "done", "failed"

    How far the Signal got. One-way: nothing returns to pending, and a failed Signal is never re-run, so error is the whole of what happened to it.

  • error string or null, required

400 application/json

The id in the path is not a uuid, or a query parameter was written.

  • statusCode integer, required
  • error string, required
  • message string, required

404 application/json

No Signal has that id.

  • statusCode integer, required
  • error string, required
  • message string, required