@sudobility/sider_types 0.0.12 → 0.0.13

package/dist/actions.d.ts

@@ -27,6 +27,66 @@ export interface ReadPageResult {
     items: ExtractedItem[];
     count: number;
 }
+/**
+ * Every tool the agent can call, named once.
+ *
+ * sider_api's decision endpoint produces one of these strings and the extension
+ * routes on it. Before this existed the name was retyped in four places — the
+ * panel's dispatch, two presentation tables, and the live harness — and nothing
+ * made them agree: `presentList` was emitted with no executor and answered
+ * "unknown tool" on every turn, so the agent kept retrying a run it had already
+ * done the work for.
+ */
+export declare const TOOL_NAMES: readonly ["readPage", "navigateTo", "siderDomAction", "callSiderTool", "attachFile", "downloadFile", "planChecklist", "presentList"];
+export type ToolName = (typeof TOOL_NAMES)[number];
+/** Everything `siderDomAction` can do to a page. */
+export declare const DOM_ACTION_TYPES: readonly ["hover", "click", "type", "select", "press", "scroll", "hold"];
+export type DomActionType = (typeof DOM_ACTION_TYPES)[number];
+/**
+ * One act on a page.
+ *
+ * `controlName` is the currency: the site graph plans in visible labels, because
+ * a selector is regenerated per render and means nothing to another user of the
+ * site. `selector` remains for exploration, when no label identifies the target,
+ * and may carry a frame prefix (see the extension's `frame-ref.ts`).
+ */
+export interface DomAction {
+    type: DomActionType;
+    controlName?: string;
+    within?: string;
+    selector?: string;
+    text?: string;
+    /** For `press` — a key name, not a character. */
+    key?: string;
+    /** For `hold` — how long to hold, in milliseconds. */
+    ms?: number;
+}
+export interface ReadPageArgs {
+    /** Free-text steer for extraction ("job listings", "prices"). */
+    hint?: string;
+}
+export interface NavigateToArgs {
+    url: string;
+}
+export interface DownloadFileArgs {
+    /** May be relative — the caller resolves it against the driven tab's origin. */
+    url: string;
+    filename?: string;
+}
+export interface AttachFileArgs {
+    /** Which of the user's attached files to use; absent means all of them. */
+    fileNames?: string[];
+    /** Which upload field, when a form has more than one. */
+    controlName?: string;
+}
+export interface CallSiderToolArgs {
+    toolId: string;
+    args?: Record<string, unknown>;
+}
+export interface PlanChecklistArgs {
+    items?: unknown[];
+    budget?: string;
+}
 /**
  * Icons a presented list may use.
  *

package/dist/actions.js

@@ -1,6 +1,36 @@
 // Structured results for the three model-facing browser actions (callSiderTool,
 // readPage, siderDomAction). One shape so the agent can aggregate outcomes and
 // report a status summary (e.g. "added 3/5; 2 pre-order only").
+/**
+ * Every tool the agent can call, named once.
+ *
+ * sider_api's decision endpoint produces one of these strings and the extension
+ * routes on it. Before this existed the name was retyped in four places — the
+ * panel's dispatch, two presentation tables, and the live harness — and nothing
+ * made them agree: `presentList` was emitted with no executor and answered
+ * "unknown tool" on every turn, so the agent kept retrying a run it had already
+ * done the work for.
+ */
+export const TOOL_NAMES = [
+    "readPage",
+    "navigateTo",
+    "siderDomAction",
+    "callSiderTool",
+    "attachFile",
+    "downloadFile",
+    "planChecklist",
+    "presentList",
+];
+/** Everything `siderDomAction` can do to a page. */
+export const DOM_ACTION_TYPES = [
+    "hover",
+    "click",
+    "type",
+    "select",
+    "press",
+    "scroll",
+    "hold",
+];
 /**
  * Icons a presented list may use.
  *

package/dist/actions.test.d.ts

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

package/dist/actions.test.js

@@ -0,0 +1,57 @@
+import { test, expect } from "bun:test";
+import { TOOL_NAMES, DOM_ACTION_TYPES } from "./actions";
+// These two arrays are a WIRE CONTRACT. sider_api emits one of these names from
+// a ShapeShyft decision endpoint and the extension routes on it; a rename on one
+// side with no matching rename on the other is exactly how `presentList` came
+// back "unknown tool" turn after turn, with the agent unable to end a run whose
+// work was already done. Pinned by value so a rename cannot pass silently.
+test("the tool name contract is exactly these eight", () => {
+    expect([...TOOL_NAMES].sort()).toEqual([
+        "attachFile",
+        "callSiderTool",
+        "downloadFile",
+        "navigateTo",
+        "planChecklist",
+        "presentList",
+        "readPage",
+        "siderDomAction",
+    ]);
+});
+test("the dom action contract is exactly these seven", () => {
+    expect([...DOM_ACTION_TYPES].sort()).toEqual([
+        "click",
+        "hold",
+        "hover",
+        "press",
+        "scroll",
+        "select",
+        "type",
+    ]);
+});
+// Exhaustiveness: a name added to the union but not the array (or the reverse)
+// fails to compile here rather than at runtime in a browser.
+test("every ToolName is present in TOOL_NAMES", () => {
+    const seen = {
+        readPage: true,
+        navigateTo: true,
+        siderDomAction: true,
+        callSiderTool: true,
+        attachFile: true,
+        downloadFile: true,
+        planChecklist: true,
+        presentList: true,
+    };
+    expect(Object.keys(seen).sort()).toEqual([...TOOL_NAMES].sort());
+});
+test("every DomActionType is present in DOM_ACTION_TYPES", () => {
+    const seen = {
+        hover: true,
+        click: true,
+        type: true,
+        select: true,
+        press: true,
+        scroll: true,
+        hold: true,
+    };
+    expect(Object.keys(seen).sort()).toEqual([...DOM_ACTION_TYPES].sort());
+});

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@sudobility/sider_types",
-	"version": "0.0.12",
+	"version": "0.0.13",
 	"description": "Shared domain types for Sider — AI assistance for generic web apps.",
 	"license": "BUSL-1.1",
 	"publishConfig": {

package/src/actions.test.ts

@@ -0,0 +1,61 @@
+import { test, expect } from "bun:test";
+import { TOOL_NAMES, DOM_ACTION_TYPES, type ToolName, type DomActionType } from "./actions";
+
+// These two arrays are a WIRE CONTRACT. sider_api emits one of these names from
+// a ShapeShyft decision endpoint and the extension routes on it; a rename on one
+// side with no matching rename on the other is exactly how `presentList` came
+// back "unknown tool" turn after turn, with the agent unable to end a run whose
+// work was already done. Pinned by value so a rename cannot pass silently.
+test("the tool name contract is exactly these eight", () => {
+  expect([...TOOL_NAMES].sort()).toEqual([
+    "attachFile",
+    "callSiderTool",
+    "downloadFile",
+    "navigateTo",
+    "planChecklist",
+    "presentList",
+    "readPage",
+    "siderDomAction",
+  ]);
+});
+
+test("the dom action contract is exactly these seven", () => {
+  expect([...DOM_ACTION_TYPES].sort()).toEqual([
+    "click",
+    "hold",
+    "hover",
+    "press",
+    "scroll",
+    "select",
+    "type",
+  ]);
+});
+
+// Exhaustiveness: a name added to the union but not the array (or the reverse)
+// fails to compile here rather than at runtime in a browser.
+test("every ToolName is present in TOOL_NAMES", () => {
+  const seen: Record<ToolName, true> = {
+    readPage: true,
+    navigateTo: true,
+    siderDomAction: true,
+    callSiderTool: true,
+    attachFile: true,
+    downloadFile: true,
+    planChecklist: true,
+    presentList: true,
+  };
+  expect(Object.keys(seen).sort()).toEqual([...TOOL_NAMES].sort());
+});
+
+test("every DomActionType is present in DOM_ACTION_TYPES", () => {
+  const seen: Record<DomActionType, true> = {
+    hover: true,
+    click: true,
+    type: true,
+    select: true,
+    press: true,
+    scroll: true,
+    hold: true,
+  };
+  expect(Object.keys(seen).sort()).toEqual([...DOM_ACTION_TYPES].sort());
+});

package/src/actions.ts

@@ -42,6 +42,94 @@ export interface ReadPageResult {
   count: number;
 }
 
+/**
+ * Every tool the agent can call, named once.
+ *
+ * sider_api's decision endpoint produces one of these strings and the extension
+ * routes on it. Before this existed the name was retyped in four places — the
+ * panel's dispatch, two presentation tables, and the live harness — and nothing
+ * made them agree: `presentList` was emitted with no executor and answered
+ * "unknown tool" on every turn, so the agent kept retrying a run it had already
+ * done the work for.
+ */
+export const TOOL_NAMES = [
+  "readPage",
+  "navigateTo",
+  "siderDomAction",
+  "callSiderTool",
+  "attachFile",
+  "downloadFile",
+  "planChecklist",
+  "presentList",
+] as const;
+
+export type ToolName = (typeof TOOL_NAMES)[number];
+
+/** Everything `siderDomAction` can do to a page. */
+export const DOM_ACTION_TYPES = [
+  "hover",
+  "click",
+  "type",
+  "select",
+  "press",
+  "scroll",
+  "hold",
+] as const;
+
+export type DomActionType = (typeof DOM_ACTION_TYPES)[number];
+
+/**
+ * One act on a page.
+ *
+ * `controlName` is the currency: the site graph plans in visible labels, because
+ * a selector is regenerated per render and means nothing to another user of the
+ * site. `selector` remains for exploration, when no label identifies the target,
+ * and may carry a frame prefix (see the extension's `frame-ref.ts`).
+ */
+export interface DomAction {
+  type: DomActionType;
+  controlName?: string;
+  within?: string;
+  selector?: string;
+  text?: string;
+  /** For `press` — a key name, not a character. */
+  key?: string;
+  /** For `hold` — how long to hold, in milliseconds. */
+  ms?: number;
+}
+
+export interface ReadPageArgs {
+  /** Free-text steer for extraction ("job listings", "prices"). */
+  hint?: string;
+}
+
+export interface NavigateToArgs {
+  url: string;
+}
+
+export interface DownloadFileArgs {
+  /** May be relative — the caller resolves it against the driven tab's origin. */
+  url: string;
+  filename?: string;
+}
+
+export interface AttachFileArgs {
+  /** Which of the user's attached files to use; absent means all of them. */
+  fileNames?: string[];
+  /** Which upload field, when a form has more than one. */
+  controlName?: string;
+}
+
+export interface CallSiderToolArgs {
+  toolId: string;
+  args?: Record<string, unknown>;
+}
+
+export interface PlanChecklistArgs {
+  items?: unknown[];
+  budget?: string;
+}
+
 /**
  * Icons a presented list may use.
  *