@g9tm/aiassistant-contracts 0.0.0-stage → 1.1.0

package/README.md

@@ -1,3 +1,22 @@
-# Temporary Holding Version
+# @g9tm/aiassistant-contracts
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Types of the G9 AI assistant's wire contracts, generated from its JSON Schemas. Types only: nothing runs, nothing is
+bundled.
+
+- `eventsV1`: a run's event log (`run.started`, `stage`, `tool`, `text.delta`, `message`, `card`, `waiting`, `result`,
+  `run.finished` and the rest), the same for streaming, long polling and a synchronous answer.
+- `blocksV1`: display blocks (table, chart, KPI, compare, timeline and the word-only blocks) with their data handles.
+- `protocolV1`: the model's reply protocol (say, call, plan, ask, load, draw, blocks).
+- `manifestV1`: a product's capability manifest (the app, its capabilities, tools with the hash of their input shape,
+  skills and custom blocks).
+- `exportV1`: one line of the neutral export, for moving an existing assistant's data into the stores.
+
+```ts
+import type { eventsV1 } from "@g9tm/aiassistant-contracts";
+
+function onEvent(e: eventsV1.RunEvent): void {
+  if (e.type === "run.finished") console.log("done at", e.at, "after", e.seq, "events");
+}
+```
+
+Part of the G9 AI assistant library. Documentation: see the guides that ship with the library.

package/dist/blocksV1.d.ts

@@ -0,0 +1,73 @@
+/**
+ * A table handle such as d1.
+ *
+ * This interface was referenced by `Blocks`'s JSON-Schema
+ * via the `definition` "handle".
+ */
+export type Handle = string;
+/**
+ * This interface was referenced by `Blocks`'s JSON-Schema
+ * via the `definition` "tone".
+ */
+export type Tone = "info" | "warn" | "ok" | "danger" | "neutral";
+/**
+ * This interface was referenced by `Blocks`'s JSON-Schema
+ * via the `definition` "chartKind".
+ */
+export type ChartKind = "bars" | "line" | "lines" | "stacked" | "donut";
+/**
+ * Display blocks. A 'blockDraft' is what a model may write: data-bearing blocks name a server-side table handle and never carry numbers. A 'block' is what the server sends to clients after filling it; every block carries a plain-text fallback.
+ */
+export interface Blocks {
+    [k: string]: unknown | undefined;
+}
+export interface BlockDraft {
+    type: string;
+}
+/**
+ * This interface was referenced by `Blocks`'s JSON-Schema
+ * via the `definition` "column".
+ */
+export interface Column {
+    name: string;
+    kind: "text" | "number" | "money" | "percent" | "date" | "day" | "id";
+    /**
+     * Already translated for the person.
+     */
+    label: string;
+}
+/**
+ * This interface was referenced by `Blocks`'s JSON-Schema
+ * via the `definition` "block".
+ */
+export interface Block {
+    type: string;
+    v: 1;
+    /**
+     * Plain text shown by a client that does not know this type.
+     */
+    fallbackText: string;
+    title?: string;
+    text?: string;
+    tone?: Tone;
+    kind?: string;
+    columns?: Column[];
+    rows?: unknown[][];
+    /**
+     * More rows exist on the server (export has them all).
+     */
+    truncated?: boolean;
+    x?: string;
+    y?: string;
+    by?: string;
+    items?: unknown[];
+    line?: string;
+    pageId?: string;
+    fileIds?: string[];
+    /**
+     * Payload of a host-defined x:* block, validated by the schema the host registered.
+     */
+    data?: {
+        [k: string]: unknown | undefined;
+    };
+}

package/dist/blocksV1.js

@@ -0,0 +1,2 @@
+/* Generated from contracts/*.schema.json by tools/codegen/generate-ts.mjs. Do not edit. */
+export {};

package/dist/eventsV1.d.ts

@@ -0,0 +1,186 @@
+/**
+ * One entry of a run's event log. Streaming, long polling and the synchronous mode are three views of the same log. 'seq' grows by one per run and is the cursor.
+ */
+export type RunEvent = {
+    seq: number;
+    type: "run.started" | "stage" | "tier" | "progress" | "tool" | "text.delta" | "message" | "card" | "waiting" | "round" | "guard" | "result" | "reconnect" | "run.finished";
+    at: string;
+    body: {};
+};
+/**
+ * This interface was referenced by `undefined`'s JSON-Schema
+ * via the `definition` "provenance".
+ */
+export type Provenance = "rule" | "learned" | "model" | "fallback" | "cached";
+/**
+ * This interface was referenced by `undefined`'s JSON-Schema
+ * via the `definition` "textLine".
+ */
+export interface TextLine {
+    key: string;
+    args?: {
+        [k: string]: string | undefined;
+    };
+}
+/**
+ * This interface was referenced by `undefined`'s JSON-Schema
+ * via the `definition` "runStarted".
+ */
+export interface RunStarted {
+    runId: string;
+    capabilityId: string;
+    conversationId?: string;
+}
+/**
+ * This interface was referenced by `undefined`'s JSON-Schema
+ * via the `definition` "stage".
+ */
+export interface Stage {
+    id: "routing" | "reading" | "thinking" | "tooling" | "checking" | "waiting" | "running" | "role";
+    state: "on" | "off";
+    role?: string;
+}
+/**
+ * This interface was referenced by `undefined`'s JSON-Schema
+ * via the `definition` "tier".
+ */
+export interface Tier {
+    tier: "t0" | "t1" | "t2" | "t3" | "offline";
+}
+/**
+ * This interface was referenced by `undefined`'s JSON-Schema
+ * via the `definition` "tool".
+ */
+export interface Tool {
+    name: string;
+    title?: TextLine;
+    state: "start" | "ok" | "fail";
+    ms?: number;
+}
+/**
+ * This interface was referenced by `undefined`'s JSON-Schema
+ * via the `definition` "textDelta".
+ */
+export interface TextDelta {
+    text: string;
+}
+/**
+ * This interface was referenced by `undefined`'s JSON-Schema
+ * via the `definition` "messageBody".
+ */
+export interface MessageBody {
+    message: Message;
+}
+/**
+ * This interface was referenced by `undefined`'s JSON-Schema
+ * via the `definition` "message".
+ */
+export interface Message {
+    id: string;
+    role: "user" | "assistant" | "system";
+    kind: "text" | "error" | "ask" | "plan" | "block" | "progress" | "files" | "learn" | "routine" | "undo";
+    text?: string;
+    blocks?: Block[];
+    next?: string[];
+    provenance?: Provenance;
+    at: string;
+}
+export interface Block {
+    type: string;
+    v: 1;
+    /**
+     * Plain text shown by a client that does not know this type.
+     */
+    fallbackText: string;
+    title?: string;
+    text?: string;
+    tone?: "info" | "warn" | "ok" | "danger" | "neutral";
+    kind?: string;
+    columns?: Column[];
+    rows?: unknown[][];
+    /**
+     * More rows exist on the server (export has them all).
+     */
+    truncated?: boolean;
+    x?: string;
+    y?: string;
+    by?: string;
+    items?: unknown[];
+    line?: string;
+    pageId?: string;
+    fileIds?: string[];
+    /**
+     * Payload of a host-defined x:* block, validated by the schema the host registered.
+     */
+    data?: {
+        [k: string]: unknown | undefined;
+    };
+}
+export interface Column {
+    name: string;
+    kind: "text" | "number" | "money" | "percent" | "date" | "day" | "id";
+    /**
+     * Already translated for the person.
+     */
+    label: string;
+}
+/**
+ * This interface was referenced by `undefined`'s JSON-Schema
+ * via the `definition` "card".
+ */
+export interface Card {
+    kind: "plan" | "ask" | "learn" | "routine" | "routine_revision" | "undo";
+    id: string;
+    body: {};
+}
+/**
+ * This interface was referenced by `undefined`'s JSON-Schema
+ * via the `definition` "waiting".
+ */
+export interface Waiting {
+    for: "confirm" | "answer";
+    id: string;
+    expiresAt?: string;
+}
+/**
+ * This interface was referenced by `undefined`'s JSON-Schema
+ * via the `definition` "round".
+ */
+export interface Round {
+    index: number;
+    modelId: string;
+    tokensIn?: number;
+    cached?: number;
+    out?: number;
+    ms?: number;
+}
+/**
+ * The structured output of a non-conversation capability (ask, one-shot, pipeline, sweep, enrichment); used is false when no model answered.
+ *
+ * This interface was referenced by `undefined`'s JSON-Schema
+ * via the `definition` "result".
+ */
+export interface Result {
+    used: boolean;
+    provenance: Provenance;
+    output?: unknown;
+    code?: string;
+}
+/**
+ * This interface was referenced by `undefined`'s JSON-Schema
+ * via the `definition` "guard".
+ */
+export interface Guard {
+    name: string;
+    pass: boolean;
+    code?: string;
+}
+/**
+ * This interface was referenced by `undefined`'s JSON-Schema
+ * via the `definition` "runFinished".
+ */
+export interface RunFinished {
+    outcome: "done" | "failed" | "cancelled";
+    code?: string;
+    provenance?: Provenance;
+}

package/dist/eventsV1.js

@@ -0,0 +1,2 @@
+/* Generated from contracts/*.schema.json by tools/codegen/generate-ts.mjs. Do not edit. */
+export {};

package/dist/exportV1.d.ts

@@ -0,0 +1,19 @@
+/**
+ * One line of a neutral export (JSON Lines). A host exports its existing assistant data in this shape; the import tool places each record in the right scope. Texts are plain (decrypted by the exporting host); the folder must be kept private and deleted after import.
+ */
+export type ExportRecord = {
+    record: "conversation" | "message" | "note" | "alias" | "routine" | "finding" | "gate" | "setting" | "usage" | "file";
+    scope: {
+        app: string;
+        space?: string;
+        realm?: string;
+        user?: string;
+        level?: "general" | "app" | "space" | "user";
+    };
+    /**
+     * The exporting host's own id, kept as a reference so related records can be linked.
+     */
+    id?: string;
+    at?: string;
+    data?: {};
+};

package/dist/exportV1.js

@@ -0,0 +1,2 @@
+/* Generated from contracts/*.schema.json by tools/codegen/generate-ts.mjs. Do not edit. */
+export {};

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export type * as blocksV1 from "./blocksV1.js";
+export type * as eventsV1 from "./eventsV1.js";
+export type * as exportV1 from "./exportV1.js";
+export type * as manifestV1 from "./manifestV1.js";
+export type * as protocolV1 from "./protocolV1.js";

package/dist/index.js

@@ -0,0 +1 @@
+export {};

package/dist/manifestV1.d.ts

@@ -0,0 +1,43 @@
+/**
+ * What a host offers its assistant, written at build time so a change is visible in review and learned items that a change would break can be listed before release.
+ */
+export interface AssistantManifest {
+    manifest: 1;
+    app: {
+        id: string;
+        realm?: string;
+        hasSpaces?: boolean;
+    };
+    capabilities: {
+        id: string;
+        kind: "conversation" | "ask" | "pipeline" | "oneShot" | "sweep" | "enrichment";
+        fastPath?: boolean;
+        guards?: string[];
+        permission?: string;
+        tier?: string;
+    }[];
+    tools: {
+        name: string;
+        group: string;
+        risk: "read" | "change" | "dangerous" | "disabled";
+        permission?: string;
+        switch?: string;
+        effects?: ("idempotent" | "undoable" | "dryRunnable" | "outbound" | "money" | "bulk")[];
+        outputTrust?: "trusted" | "untrusted";
+        core?: boolean;
+        hiddenNames?: string[];
+        schemaHash: string;
+    }[];
+    skills: {
+        name: string;
+        parent?: string;
+        group?: string;
+        budget: number;
+        locked?: boolean;
+        kind?: "skill" | "runbook";
+        hash: string;
+    }[];
+    instantRules?: string[];
+    routineSeeds?: string[];
+    blocks?: string[];
+}

package/dist/manifestV1.js

@@ -0,0 +1,2 @@
+/* Generated from contracts/*.schema.json by tools/codegen/generate-ts.mjs. Do not edit. */
+export {};

package/dist/protocolV1.d.ts

@@ -0,0 +1,136 @@
+/**
+ * What a model writes in the JSON dialect: exactly one object per turn. 'say' alone ends the turn; at most one of call, plan, ask, load and draw asks the server to act. Display fields are allowed only when no action is present.
+ */
+export type AssistantReply = {
+    [k: string]: unknown | undefined;
+} & ({
+    say: {
+        [k: string]: unknown | undefined;
+    };
+} | {
+    [k: string]: unknown | undefined;
+}) & {
+    /**
+     * Text for the person.
+     */
+    say?: string;
+    call?: Call;
+    plan?: Plan;
+    ask?: Ask;
+    load?: Load;
+    draw?: Draw;
+    /**
+     * @maxItems 8
+     */
+    blocks?: BlockDraft[];
+    /**
+     * @maxItems 4
+     */
+    next?: string[];
+    /**
+     * Something the person said that is worth keeping; the server decides whether it may become a note.
+     */
+    learn?: string;
+    /**
+     * @maxItems 3
+     */
+    flags?: Flag[];
+    /**
+     * A page id the host knows by name.
+     */
+    open?: string;
+};
+/**
+ * This interface was referenced by `undefined`'s JSON-Schema
+ * via the `definition` "toolName".
+ */
+export type ToolName = string;
+/**
+ * This interface was referenced by `undefined`'s JSON-Schema
+ * via the `definition` "load".
+ */
+export type Load = Load1 & {
+    /**
+     * @maxItems 4
+     */
+    skills?: string[];
+    /**
+     * @maxItems 8
+     */
+    tools?: string[];
+};
+export type Load1 = {
+    [k: string]: unknown | undefined;
+};
+export type BlockDraft = {
+    type: string;
+};
+/**
+ * This interface was referenced by `undefined`'s JSON-Schema
+ * via the `definition` "call".
+ */
+export interface Call {
+    tool: ToolName;
+    input?: {};
+}
+/**
+ * This interface was referenced by `undefined`'s JSON-Schema
+ * via the `definition` "plan".
+ */
+export interface Plan {
+    title: string;
+    more?: boolean;
+    /**
+     * @minItems 1
+     * @maxItems 30
+     */
+    steps: [PlanStep, ...PlanStep[]];
+}
+/**
+ * This interface was referenced by `undefined`'s JSON-Schema
+ * via the `definition` "planStep".
+ */
+export interface PlanStep {
+    tool: ToolName;
+    input?: {};
+    text?: string;
+}
+/**
+ * This interface was referenced by `undefined`'s JSON-Schema
+ * via the `definition` "ask".
+ */
+export interface Ask {
+    question: string;
+    /**
+     * @maxItems 12
+     */
+    options?: AskOption[];
+    multi?: boolean;
+    /**
+     * Ask the person for a secret by name; the value never reaches the model.
+     */
+    secret?: string;
+}
+/**
+ * This interface was referenced by `undefined`'s JSON-Schema
+ * via the `definition` "askOption".
+ */
+export interface AskOption {
+    label: string;
+    hint?: string;
+}
+/**
+ * This interface was referenced by `undefined`'s JSON-Schema
+ * via the `definition` "draw".
+ */
+export interface Draw {
+    prompt: string;
+}
+/**
+ * This interface was referenced by `undefined`'s JSON-Schema
+ * via the `definition` "flag".
+ */
+export interface Flag {
+    key: string;
+    text: string;
+}

package/dist/protocolV1.js

@@ -0,0 +1,2 @@
+/* Generated from contracts/*.schema.json by tools/codegen/generate-ts.mjs. Do not edit. */
+export {};

package/package.json

@@ -1,6 +1,31 @@
 {
   "name": "@g9tm/aiassistant-contracts",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.1.0",
+  "description": "Types of the G9 AI assistant wire contracts, generated from the JSON Schemas.",
+  "license": "MIT",
+  "author": {
+    "name": "Iman Kari",
+    "url": "G9TM"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
 }