@handstage/agent 1.0.0

package/src/schemas.ts

@@ -0,0 +1,207 @@
+import { z } from "zod"
+
+export const LoadStateSchema = z
+	.enum(["load", "domcontentloaded", "networkidle"])
+	.optional()
+	.describe("Wait until this lifecycle event (navigation / reload / history)")
+
+export const PageIdSchema = z
+	.string()
+	.describe("Target id of the page tab (from pages or newPage)")
+
+export const PagesInputSchema = z.object({})
+
+export const NewPageInputSchema = z.object({
+	url: z.string().optional().describe('Initial URL (default "about:blank")'),
+})
+
+export const BringToFrontInputSchema = z.object({ pageId: PageIdSchema })
+
+export const ClosePageInputSchema = z.object({ pageId: PageIdSchema })
+
+export const GotoInputSchema = z.object({
+	pageId: PageIdSchema,
+	url: z.string().min(1),
+	waitUntil: LoadStateSchema,
+	timeoutMs: z.number().positive().optional(),
+})
+
+export const ReloadInputSchema = z.object({
+	pageId: PageIdSchema,
+	waitUntil: LoadStateSchema,
+	timeoutMs: z.number().positive().optional(),
+	ignoreCache: z.boolean().optional(),
+})
+
+export const GoBackInputSchema = z.object({
+	pageId: PageIdSchema,
+	waitUntil: LoadStateSchema,
+	timeoutMs: z.number().positive().optional(),
+})
+
+export const GoForwardInputSchema = z.object({
+	pageId: PageIdSchema,
+	waitUntil: LoadStateSchema,
+	timeoutMs: z.number().positive().optional(),
+})
+
+export const SnapshotDomInputSchema = z.object({
+	pageId: PageIdSchema,
+	includeIframes: z.boolean().optional(),
+})
+
+export const PageInfoInputSchema = z.object({ pageId: PageIdSchema })
+
+export const ClickInputSchema = z.object({
+	pageId: PageIdSchema,
+	x: z.number(),
+	y: z.number(),
+	button: z.enum(["left", "right", "middle"]).optional(),
+	clickCount: z.number().int().positive().optional(),
+})
+
+export const HoverInputSchema = z.object({
+	pageId: PageIdSchema,
+	x: z.number(),
+	y: z.number(),
+})
+
+export const ScrollInputSchema = z.object({
+	pageId: PageIdSchema,
+	x: z.number(),
+	y: z.number(),
+	deltaX: z.number(),
+	deltaY: z.number(),
+})
+
+export const TypeInputSchema = z.object({
+	pageId: PageIdSchema,
+	text: z.string(),
+	delay: z.number().nonnegative().optional(),
+	withMistakes: z.boolean().optional(),
+})
+
+export const ClickOnInputSchema = z.object({
+	pageId: PageIdSchema,
+	select: z
+		.string()
+		.min(1)
+		.describe("CSS selector or XPath (e.g. //button[@id='x'])"),
+})
+
+export const FillOnInputSchema = z.object({
+	pageId: PageIdSchema,
+	select: z.string().min(1).describe("CSS selector or XPath"),
+	value: z.string(),
+})
+
+export const TypeOnInputSchema = z.object({
+	pageId: PageIdSchema,
+	select: z.string().min(1).describe("CSS selector or XPath"),
+	text: z.string(),
+	delay: z.number().nonnegative().optional(),
+})
+
+export const HoverOnInputSchema = z.object({
+	pageId: PageIdSchema,
+	select: z.string().min(1).describe("CSS selector or XPath"),
+})
+
+/** Encoded node id from snapshot_dom (e.g. `1-42` — frameOrdinal-backendNodeId). */
+export const A11yEncodedIdSchema = z
+	.string()
+	.min(1)
+	.regex(/^\d+-\d+$/, "Expected frameOrdinal-backendNodeId from snapshot_dom")
+	.describe("Encoded node id from snapshot_dom (bracketed id in the a11y tree)")
+
+export const ClickOnIdInputSchema = z.object({
+	pageId: PageIdSchema,
+	id: A11yEncodedIdSchema,
+})
+
+export const FillOnIdInputSchema = z.object({
+	pageId: PageIdSchema,
+	id: A11yEncodedIdSchema,
+	value: z.string(),
+})
+
+export const TypeOnIdInputSchema = z.object({
+	pageId: PageIdSchema,
+	id: A11yEncodedIdSchema,
+	text: z.string(),
+	delay: z.number().nonnegative().optional(),
+})
+
+export const HoverOnIdInputSchema = z.object({
+	pageId: PageIdSchema,
+	id: A11yEncodedIdSchema,
+})
+
+/** Shared `{ ok: true } | { ok: false; error }` tool result shape */
+export const HandstageAgentOkOrErrOutputSchema = z.discriminatedUnion("ok", [
+	z.object({ ok: z.literal(true) }),
+	z.object({ ok: z.literal(false), error: z.string() }),
+])
+
+export const HandstageAgentPageEntrySchema = z.object({
+	pageId: z.string(),
+	url: z.string(),
+	title: z.string(),
+})
+
+export const PagesOutputSchema = z.object({
+	pages: z.array(HandstageAgentPageEntrySchema),
+})
+
+export const NewPageOutputSchema = z.object({ pageId: z.string() })
+
+export const BringToFrontOutputSchema = HandstageAgentOkOrErrOutputSchema
+
+export const ClosePageOutputSchema = HandstageAgentOkOrErrOutputSchema
+
+export const GotoOutputSchema = z.discriminatedUnion("ok", [
+	z.object({ ok: z.literal(true), url: z.string() }),
+	z.object({ ok: z.literal(false), error: z.string() }),
+])
+
+export const ReloadOutputSchema = GotoOutputSchema
+
+export const HistoryNavOutputSchema = z.discriminatedUnion("ok", [
+	z.object({
+		ok: z.literal(true),
+		navigated: z.boolean(),
+		url: z.string(),
+	}),
+	z.object({ ok: z.literal(false), error: z.string() }),
+])
+
+export const SnapshotDomOutputSchema = z.discriminatedUnion("ok", [
+	z.object({
+		ok: z.literal(true),
+		tree: z.string(),
+		xpathMap: z.record(z.string(), z.string()),
+		urlMap: z.record(z.string(), z.string()),
+	}),
+	z.object({ ok: z.literal(false), error: z.string() }),
+])
+
+export const PageInfoOutputSchema = z.discriminatedUnion("ok", [
+	z.object({
+		ok: z.literal(true),
+		url: z.string(),
+		title: z.string(),
+	}),
+	z.object({ ok: z.literal(false), error: z.string() }),
+])
+
+export const PointerOutputSchema = z.discriminatedUnion("ok", [
+	z.object({
+		ok: z.literal(true),
+		xpathAtPoint: z.string().optional(),
+	}),
+	z.object({ ok: z.literal(false), error: z.string() }),
+])
+
+export const TypeOutputSchema = HandstageAgentOkOrErrOutputSchema
+
+export const ElementActionOutputSchema = HandstageAgentOkOrErrOutputSchema

package/src/types.ts

@@ -0,0 +1,108 @@
+import type { z } from "zod"
+import type {
+	// ClickInputSchema,
+	ClickOnIdInputSchema,
+	// BringToFrontInputSchema,
+	// BringToFrontOutputSchema,
+	ClosePageInputSchema,
+	ClosePageOutputSchema,
+	// ClickOnInputSchema,
+	ElementActionOutputSchema,
+	FillOnIdInputSchema,
+	// FillOnInputSchema,
+	GoBackInputSchema,
+	GoForwardInputSchema,
+	GotoInputSchema,
+	GotoOutputSchema,
+	HandstageAgentPageEntrySchema,
+	HistoryNavOutputSchema,
+	// HoverInputSchema,
+	HoverOnIdInputSchema,
+	// HoverOnInputSchema,
+	NewPageInputSchema,
+	NewPageOutputSchema,
+	// PageInfoInputSchema,
+	// PageInfoOutputSchema,
+	PagesInputSchema,
+	PagesOutputSchema,
+	// PointerOutputSchema,
+	ReloadInputSchema,
+	ReloadOutputSchema,
+	// ScrollInputSchema,
+	SnapshotDomInputSchema,
+	SnapshotDomOutputSchema,
+	// TypeInputSchema,
+	TypeOnIdInputSchema,
+	// TypeOnInputSchema,
+	// TypeOutputSchema,
+} from "./schemas"
+
+export type PagesInput = z.infer<typeof PagesInputSchema>
+export type PagesOutput = z.infer<typeof PagesOutputSchema>
+export type PageEntry = z.infer<typeof HandstageAgentPageEntrySchema>
+
+export type NewPageInput = z.infer<typeof NewPageInputSchema>
+export type NewPageOutput = z.infer<typeof NewPageOutputSchema>
+
+// export type BringToFrontInput = z.infer<typeof BringToFrontInputSchema>
+// export type BringToFrontOutput = z.infer<typeof BringToFrontOutputSchema>
+
+export type ClosePageInput = z.infer<typeof ClosePageInputSchema>
+export type ClosePageOutput = z.infer<typeof ClosePageOutputSchema>
+
+export type GotoInput = z.infer<typeof GotoInputSchema>
+export type GotoOutput = z.infer<typeof GotoOutputSchema>
+
+export type ReloadInput = z.infer<typeof ReloadInputSchema>
+export type ReloadOutput = z.infer<typeof ReloadOutputSchema>
+
+export type GoBackInput = z.infer<typeof GoBackInputSchema>
+export type GoBackOutput = z.infer<typeof HistoryNavOutputSchema>
+
+export type GoForwardInput = z.infer<typeof GoForwardInputSchema>
+export type GoForwardOutput = z.infer<typeof HistoryNavOutputSchema>
+
+export type SnapshotDomInput = z.infer<typeof SnapshotDomInputSchema>
+export type SnapshotDomOutput = z.infer<typeof SnapshotDomOutputSchema>
+
+// export type PageInfoInput = z.infer<typeof PageInfoInputSchema>
+// export type PageInfoOutput = z.infer<typeof PageInfoOutputSchema>
+
+// export type ClickInput = z.infer<typeof ClickInputSchema>
+// export type ClickOutput = z.infer<typeof PointerOutputSchema>
+
+// export type HoverInput = z.infer<typeof HoverInputSchema>
+// export type HoverOutput = z.infer<typeof PointerOutputSchema>
+
+// export type ScrollInput = z.infer<typeof ScrollInputSchema>
+// export type ScrollOutput = z.infer<typeof PointerOutputSchema>
+
+// export type TypeInput = z.infer<typeof TypeInputSchema>
+// export type TypeOutput = z.infer<typeof TypeOutputSchema>
+
+// export type ClickOnInput = z.infer<typeof ClickOnInputSchema>
+// export type ClickOnOutput = z.infer<typeof ElementActionOutputSchema>
+
+// export type FillOnInput = z.infer<typeof FillOnInputSchema>
+// export type FillOnOutput = z.infer<typeof ElementActionOutputSchema>
+
+// export type TypeOnInput = z.infer<typeof TypeOnInputSchema>
+// export type TypeOnOutput = z.infer<typeof ElementActionOutputSchema>
+
+// export type HoverOnInput = z.infer<typeof HoverOnInputSchema>
+// export type HoverOnOutput = z.infer<typeof ElementActionOutputSchema>
+
+export type ClickOnIdInput = z.infer<typeof ClickOnIdInputSchema>
+export type ClickOnIdOutput = z.infer<typeof ElementActionOutputSchema>
+
+export type FillOnIdInput = z.infer<typeof FillOnIdInputSchema>
+export type FillOnIdOutput = z.infer<typeof ElementActionOutputSchema>
+
+export type TypeOnIdInput = z.infer<typeof TypeOnIdInputSchema>
+export type TypeOnIdOutput = z.infer<typeof ElementActionOutputSchema>
+
+export type HoverOnIdInput = z.infer<typeof HoverOnIdInputSchema>
+export type HoverOnIdOutput = z.infer<typeof ElementActionOutputSchema>
+
+export type OkResult = Extract<ClickOnIdOutput, { ok: true }>
+export type ErrResult = Extract<ClickOnIdOutput, { ok: false }>