@terreno/blocks 57.10.1

package/schemas/pendingAsksResponse.schema.json

@@ -0,0 +1,195 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "description": "The response body of GET /gpt/histories/pendingAsks: the caller's pending asks, newest first.",
+  "title": "PendingAsksResponse",
+  "type": "object",
+  "properties": {
+    "data": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "created": {
+            "type": "string",
+            "format": "date-time",
+            "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$",
+            "description": "When the agent asked, as an ISO 8601 UTC timestamp."
+          },
+          "historyId": {
+            "type": "string",
+            "minLength": 1,
+            "description": "The conversation the ask belongs to."
+          },
+          "kind": {
+            "type": "string",
+            "enum": [
+              "choice",
+              "confirm",
+              "markdown",
+              "form",
+              "files"
+            ]
+          },
+          "simple": {
+            "type": "object",
+            "properties": {
+              "buttons": {
+                "maxItems": 3,
+                "type": "array",
+                "items": {
+                  "type": "object",
+                  "properties": {
+                    "id": {
+                      "type": "string",
+                      "minLength": 1
+                    },
+                    "label": {
+                      "type": "string",
+                      "minLength": 1,
+                      "maxLength": 20
+                    },
+                    "response": {
+                      "oneOf": [
+                        {
+                          "type": "object",
+                          "properties": {
+                            "action": {
+                              "type": "string",
+                              "const": "accept"
+                            },
+                            "content": {
+                              "type": "object",
+                              "propertyNames": {
+                                "type": "string"
+                              },
+                              "additionalProperties": {}
+                            }
+                          },
+                          "required": [
+                            "action",
+                            "content"
+                          ],
+                          "additionalProperties": false
+                        },
+                        {
+                          "type": "object",
+                          "properties": {
+                            "action": {
+                              "type": "string",
+                              "const": "decline"
+                            }
+                          },
+                          "required": [
+                            "action"
+                          ],
+                          "additionalProperties": false
+                        },
+                        {
+                          "type": "object",
+                          "properties": {
+                            "action": {
+                              "type": "string",
+                              "const": "cancel"
+                            },
+                            "reason": {
+                              "type": "string",
+                              "minLength": 1,
+                              "maxLength": 200
+                            }
+                          },
+                          "required": [
+                            "action"
+                          ],
+                          "additionalProperties": false
+                        }
+                      ],
+                      "title": "AskResponse"
+                    },
+                    "style": {
+                      "type": "string",
+                      "enum": [
+                        "default",
+                        "primary",
+                        "destructive",
+                        "cancel"
+                      ]
+                    }
+                  },
+                  "required": [
+                    "id",
+                    "label",
+                    "response",
+                    "style"
+                  ],
+                  "additionalProperties": false,
+                  "title": "SimpleCardButton"
+                }
+              },
+              "handoff": {
+                "type": "boolean"
+              },
+              "kind": {
+                "type": "string",
+                "enum": [
+                  "choice",
+                  "confirm",
+                  "markdown",
+                  "form",
+                  "files"
+                ]
+              },
+              "text": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 140
+              },
+              "title": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 40
+              },
+              "toolCallId": {
+                "type": "string",
+                "minLength": 1
+              }
+            },
+            "required": [
+              "buttons",
+              "handoff",
+              "kind",
+              "text",
+              "toolCallId"
+            ],
+            "additionalProperties": false,
+            "title": "SimpleCard"
+          },
+          "title": {
+            "description": "The conversation's title, once it has one.",
+            "type": "string"
+          },
+          "toolCallId": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "required": [
+          "created",
+          "historyId",
+          "kind",
+          "simple",
+          "toolCallId"
+        ],
+        "additionalProperties": false,
+        "title": "PendingAsk"
+      }
+    },
+    "requestId": {
+      "description": "The request's id. Apps built with TerrenoApp add it to every JSON response; quote it when reporting a problem.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "data"
+  ],
+  "additionalProperties": false
+}

package/schemas/simpleCard.schema.json

@@ -0,0 +1,135 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "description": "The small-screen form of an ask: short text and at most three buttons, each carrying the exact answer it sends. Button ids are unique within a card, which JSON Schema cannot express.",
+  "title": "SimpleCard",
+  "type": "object",
+  "properties": {
+    "buttons": {
+      "maxItems": 3,
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "string",
+            "minLength": 1
+          },
+          "label": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 20
+          },
+          "response": {
+            "oneOf": [
+              {
+                "type": "object",
+                "properties": {
+                  "action": {
+                    "type": "string",
+                    "const": "accept"
+                  },
+                  "content": {
+                    "type": "object",
+                    "propertyNames": {
+                      "type": "string"
+                    },
+                    "additionalProperties": {}
+                  }
+                },
+                "required": [
+                  "action",
+                  "content"
+                ],
+                "additionalProperties": false
+              },
+              {
+                "type": "object",
+                "properties": {
+                  "action": {
+                    "type": "string",
+                    "const": "decline"
+                  }
+                },
+                "required": [
+                  "action"
+                ],
+                "additionalProperties": false
+              },
+              {
+                "type": "object",
+                "properties": {
+                  "action": {
+                    "type": "string",
+                    "const": "cancel"
+                  },
+                  "reason": {
+                    "type": "string",
+                    "minLength": 1,
+                    "maxLength": 200
+                  }
+                },
+                "required": [
+                  "action"
+                ],
+                "additionalProperties": false
+              }
+            ],
+            "title": "AskResponse"
+          },
+          "style": {
+            "type": "string",
+            "enum": [
+              "default",
+              "primary",
+              "destructive",
+              "cancel"
+            ]
+          }
+        },
+        "required": [
+          "id",
+          "label",
+          "response",
+          "style"
+        ],
+        "additionalProperties": false,
+        "title": "SimpleCardButton"
+      }
+    },
+    "handoff": {
+      "type": "boolean"
+    },
+    "kind": {
+      "type": "string",
+      "enum": [
+        "choice",
+        "confirm",
+        "markdown",
+        "form",
+        "files"
+      ]
+    },
+    "text": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 140
+    },
+    "title": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 40
+    },
+    "toolCallId": {
+      "type": "string",
+      "minLength": 1
+    }
+  },
+  "required": [
+    "buttons",
+    "handoff",
+    "kind",
+    "text",
+    "toolCallId"
+  ],
+  "additionalProperties": false
+}

package/schemas/turnRequest.schema.json

@@ -0,0 +1,108 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "description": "The request body of POST /gpt/histories/{id}/turn. Send exactly one of prompt, askResponse, or toolCallId with buttonId, plus an optional surface. JSON Schema cannot express that rule; the server enforces it.",
+  "title": "TurnRequest",
+  "type": "object",
+  "properties": {
+    "askResponse": {
+      "description": "A full answer to the pending ask, as a client that renders the ask sends it.",
+      "oneOf": [
+        {
+          "type": "object",
+          "properties": {
+            "action": {
+              "type": "string",
+              "const": "accept"
+            },
+            "content": {
+              "type": "object",
+              "propertyNames": {
+                "type": "string"
+              },
+              "additionalProperties": {}
+            },
+            "toolCallId": {
+              "type": "string",
+              "minLength": 1,
+              "description": "The pending ask's toolCallId."
+            }
+          },
+          "required": [
+            "action",
+            "content",
+            "toolCallId"
+          ],
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "properties": {
+            "action": {
+              "type": "string",
+              "const": "decline"
+            },
+            "toolCallId": {
+              "type": "string",
+              "minLength": 1,
+              "description": "The pending ask's toolCallId."
+            }
+          },
+          "required": [
+            "action",
+            "toolCallId"
+          ],
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "properties": {
+            "action": {
+              "type": "string",
+              "const": "cancel"
+            },
+            "reason": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 200
+            },
+            "toolCallId": {
+              "type": "string",
+              "minLength": 1,
+              "description": "The pending ask's toolCallId."
+            }
+          },
+          "required": [
+            "action",
+            "toolCallId"
+          ],
+          "additionalProperties": false
+        }
+      ],
+      "title": "AskAnswer"
+    },
+    "buttonId": {
+      "description": "The id of the simple card button the user pressed. Send it with toolCallId.",
+      "type": "string",
+      "minLength": 1
+    },
+    "prompt": {
+      "description": "A new message from the user. It cancels the pending ask, if there is one.",
+      "type": "string",
+      "minLength": 1
+    },
+    "surface": {
+      "type": "string",
+      "enum": [
+        "full",
+        "compact"
+      ],
+      "description": "Where the user answers. \"compact\" is a watch or another small screen: the agent asks only questions whose buttons show every option, and keeps replies to two short sentences. Defaults to \"full\"."
+    },
+    "toolCallId": {
+      "type": "string",
+      "minLength": 1,
+      "description": "The pending ask's toolCallId."
+    }
+  },
+  "additionalProperties": false
+}

package/schemas/turnResponse.schema.json

@@ -0,0 +1,204 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "description": "The response body of POST /gpt/histories/{id}/turn, sent once the turn finishes.",
+  "title": "TurnResponse",
+  "type": "object",
+  "properties": {
+    "data": {
+      "type": "object",
+      "properties": {
+        "error": {
+          "description": "Set when the turn failed after it started. text holds what the agent said before the error.",
+          "type": "string"
+        },
+        "historyId": {
+          "type": "string",
+          "minLength": 1,
+          "description": "The conversation's id."
+        },
+        "pendingAsk": {
+          "type": "object",
+          "properties": {
+            "kind": {
+              "type": "string",
+              "enum": [
+                "choice",
+                "confirm",
+                "markdown",
+                "form",
+                "files"
+              ]
+            },
+            "simple": {
+              "type": "object",
+              "properties": {
+                "buttons": {
+                  "maxItems": 3,
+                  "type": "array",
+                  "items": {
+                    "type": "object",
+                    "properties": {
+                      "id": {
+                        "type": "string",
+                        "minLength": 1
+                      },
+                      "label": {
+                        "type": "string",
+                        "minLength": 1,
+                        "maxLength": 20
+                      },
+                      "response": {
+                        "oneOf": [
+                          {
+                            "type": "object",
+                            "properties": {
+                              "action": {
+                                "type": "string",
+                                "const": "accept"
+                              },
+                              "content": {
+                                "type": "object",
+                                "propertyNames": {
+                                  "type": "string"
+                                },
+                                "additionalProperties": {}
+                              }
+                            },
+                            "required": [
+                              "action",
+                              "content"
+                            ],
+                            "additionalProperties": false
+                          },
+                          {
+                            "type": "object",
+                            "properties": {
+                              "action": {
+                                "type": "string",
+                                "const": "decline"
+                              }
+                            },
+                            "required": [
+                              "action"
+                            ],
+                            "additionalProperties": false
+                          },
+                          {
+                            "type": "object",
+                            "properties": {
+                              "action": {
+                                "type": "string",
+                                "const": "cancel"
+                              },
+                              "reason": {
+                                "type": "string",
+                                "minLength": 1,
+                                "maxLength": 200
+                              }
+                            },
+                            "required": [
+                              "action"
+                            ],
+                            "additionalProperties": false
+                          }
+                        ],
+                        "title": "AskResponse"
+                      },
+                      "style": {
+                        "type": "string",
+                        "enum": [
+                          "default",
+                          "primary",
+                          "destructive",
+                          "cancel"
+                        ]
+                      }
+                    },
+                    "required": [
+                      "id",
+                      "label",
+                      "response",
+                      "style"
+                    ],
+                    "additionalProperties": false,
+                    "title": "SimpleCardButton"
+                  }
+                },
+                "handoff": {
+                  "type": "boolean"
+                },
+                "kind": {
+                  "type": "string",
+                  "enum": [
+                    "choice",
+                    "confirm",
+                    "markdown",
+                    "form",
+                    "files"
+                  ]
+                },
+                "text": {
+                  "type": "string",
+                  "minLength": 1,
+                  "maxLength": 140
+                },
+                "title": {
+                  "type": "string",
+                  "minLength": 1,
+                  "maxLength": 40
+                },
+                "toolCallId": {
+                  "type": "string",
+                  "minLength": 1
+                }
+              },
+              "required": [
+                "buttons",
+                "handoff",
+                "kind",
+                "text",
+                "toolCallId"
+              ],
+              "additionalProperties": false,
+              "title": "SimpleCard"
+            },
+            "toolCallId": {
+              "type": "string",
+              "minLength": 1
+            }
+          },
+          "required": [
+            "kind",
+            "simple",
+            "toolCallId"
+          ],
+          "additionalProperties": false,
+          "description": "The ask the turn paused on. Answer it with its toolCallId and the id of one of simple.buttons.",
+          "title": "PendingAskSummary"
+        },
+        "text": {
+          "type": "string",
+          "description": "The agent's reply, or an empty string when it only asked."
+        },
+        "title": {
+          "description": "The conversation's title, once it has one.",
+          "type": "string"
+        }
+      },
+      "required": [
+        "historyId",
+        "text"
+      ],
+      "additionalProperties": false,
+      "title": "TurnResult"
+    },
+    "requestId": {
+      "description": "The request's id. Apps built with TerrenoApp add it to every JSON response; quote it when reporting a problem.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "data"
+  ],
+  "additionalProperties": false
+}

package/scripts/writeJsonSchemas.ts

@@ -0,0 +1,11 @@
+import {mkdirSync, writeFileSync} from "node:fs";
+import {join} from "node:path";
+import {askJsonSchemas} from "../src/asks/jsonSchema";
+
+const SCHEMAS_DIR = join(import.meta.dir, "..", "schemas");
+
+mkdirSync(SCHEMAS_DIR, {recursive: true});
+for (const [fileName, document] of Object.entries(askJsonSchemas())) {
+  writeFileSync(join(SCHEMAS_DIR, fileName), `${JSON.stringify(document, null, 2)}\n`);
+  console.info(`Wrote schemas/${fileName}`);
+}