@jini-ai/agentic 0.1.2 → 0.3.0

package/dist/core/guards.d.ts

@@ -0,0 +1,96 @@
+/**
+ * @module guards
+ *
+ * The refusals that must hold on every surface, expressed over plain descriptors rather than
+ * DOM nodes so they are testable in Node and reusable from any framework binding.
+ *
+ * Both guards here answer review findings that an allowlist alone does not cover: a generic
+ * filler will happily type into a password or card-number field even when that field carries a
+ * legitimate handle, and `data-agent-label` is page-authored text that reaches a model as if
+ * the host had written it.
+ */
+/** The subset of an input element these guards need. Framework- and DOM-free by design. */
+export interface FieldDescriptor {
+    /** The `type` attribute, lowercased. */
+    readonly type?: string | undefined;
+    /** The `autocomplete` attribute, lowercased. */
+    readonly autocomplete?: string | undefined;
+    readonly name?: string | undefined;
+    readonly id?: string | undefined;
+    /**
+     * **Every** human-visible naming of the field the driver could resolve — `aria-label`,
+     * `placeholder`, and the text of each associated `<label>`.
+     *
+     * Carried because `name`/`id` are the *machine* names, and a form builder or CMS that emits
+     * `name="field_47"` leaves the guard nothing to judge while the page still plainly reads
+     * "Card number" to the user. A field whose sensitivity is stated only in its label was
+     * invisible to every refusal here until this existed.
+     *
+     * Plural, and required to be exhaustive, because the singular form this replaced took whichever
+     * source resolved *first*: a page could then mask a sensitive field behind a benign one —
+     * `<label for=f>Card number</label><input id=f name=field_47 placeholder="Enter value">` reached
+     * the guard as the single label "Enter value", and its value was reported back in full.
+     */
+    readonly accessibleLabels?: readonly string[] | undefined;
+    readonly readOnly?: boolean | undefined;
+    readonly disabled?: boolean | undefined;
+}
+/**
+ * The refusals that are about *secrecy* — the field's contents are not an agent's to know.
+ *
+ * Separated from the two writability refusals below because reading and writing are different
+ * questions with different answers. A read-only field's value is perfectly safe to read back; a
+ * password's is not safe to read even though it is, mechanically, just as readable. Folding both
+ * into one list would either leak the password or hide the read-only field's value for no reason.
+ */
+export type FieldReadRefusal = 'denied-type' | 'denied-autocomplete' | 'suspicious-name';
+export type FieldRefusal = FieldReadRefusal | 'not-text' | 'read-only' | 'disabled';
+/**
+ * Why this field's current value must not be reported back to a caller, or `null` when reading
+ * it is safe.
+ *
+ * Reading is the strictly more dangerous direction: writing into a password box gives an agent
+ * nothing, whereas reading one out hands over the secret itself. So every secrecy signal the fill
+ * guard uses applies here identically — type, autocomplete token, and a name or id that indicates
+ * a credential or anti-forgery token — and none of them may be relaxed for reads.
+ *
+ * @param field - The field's attributes.
+ * @returns The first secrecy refusal, or `null` when the value may be reported.
+ */
+export declare function findFieldReadRefusal(field: FieldDescriptor): FieldReadRefusal | null;
+/**
+ * Why an automated fill must be refused for this field, or `null` when it is safe to write.
+ *
+ * Fails closed on anything that looks like a credential, payment instrument, one-time code, or
+ * anti-forgery token, independent of whether the field carries an agent handle. Tagging a
+ * password box does not make it fillable. Every secrecy refusal is also a fill refusal — a field
+ * whose contents an agent may not read is certainly not one it may overwrite — and two further
+ * refusals cover fields that are simply not writable.
+ *
+ * @param field - The field's attributes.
+ * @returns The first refusal reason, or `null` when the field may be filled.
+ */
+export declare function findFieldFillRefusal(field: FieldDescriptor): FieldRefusal | null;
+/** Model-readable reason for a refusal, so a blocked fill explains itself instead of failing opaquely. */
+export declare function describeFieldRefusal(refusal: FieldRefusal): string;
+/** Model-readable reason a value was withheld, so a caller knows the field has contents it may not see rather than assuming it is empty. */
+export declare function describeFieldReadRefusal(refusal: FieldReadRefusal): string;
+/** Default cap on page-authored text handed to a model. */
+export declare const MAX_AGENT_LABEL_LENGTH = 200;
+export interface NormalizedLabel {
+    readonly text: string;
+    readonly truncated: boolean;
+}
+/**
+ * Normalizes page-authored text before it reaches a model.
+ *
+ * Strips control characters (including the bidirectional overrides used to make text render
+ * differently from how it reads), collapses whitespace, and caps the length. The result is still
+ * untrusted *content* — this only bounds it; it does not make it safe to follow as instruction.
+ *
+ * @param raw - Text read off the page, e.g. a `data-agent-label`.
+ * @param maxLength - Cap, defaulting to {@link MAX_AGENT_LABEL_LENGTH}.
+ * @returns The bounded text and whether anything was cut.
+ */
+export declare function normalizeAgentLabel(raw: string, maxLength?: number): NormalizedLabel;
+//# sourceMappingURL=guards.d.ts.map

package/dist/core/guards.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guards.d.ts","sourceRoot":"","sources":["../../src/core/guards.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,2FAA2F;AAC3F,MAAM,WAAW,eAAe;IAC9B,wCAAwC;IACxC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,gDAAgD;IAChD,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3C,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC;;;;;;;;;;;;;OAaG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;IAC1D,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACxC,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CACzC;AAuDD;;;;;;;GAOG;AACH,MAAM,MAAM,gBAAgB,GACxB,aAAa,GACb,qBAAqB,GACrB,iBAAiB,CAAC;AAYtB,MAAM,MAAM,YAAY,GAAG,gBAAgB,GAAG,UAAU,GAAG,WAAW,GAAG,UAAU,CAAC;AAEpF;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,eAAe,GAAG,gBAAgB,GAAG,IAAI,CA+BpF;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,eAAe,GAAG,YAAY,GAAG,IAAI,CAQhF;AAiBD,0GAA0G;AAC1G,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,YAAY,GAAG,MAAM,CAElE;AAED,4IAA4I;AAC5I,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,gBAAgB,GAAG,MAAM,CAE1E;AAED,2DAA2D;AAC3D,eAAO,MAAM,sBAAsB,MAAM,CAAC;AAa1C,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC7B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,SAAyB,GAAG,eAAe,CAKpG"}

package/dist/core/guards.js

@@ -0,0 +1,186 @@
+/**
+ * @module guards
+ *
+ * The refusals that must hold on every surface, expressed over plain descriptors rather than
+ * DOM nodes so they are testable in Node and reusable from any framework binding.
+ *
+ * Both guards here answer review findings that an allowlist alone does not cover: a generic
+ * filler will happily type into a password or card-number field even when that field carries a
+ * legitimate handle, and `data-agent-label` is page-authored text that reaches a model as if
+ * the host had written it.
+ */
+/** Input types no automated caller may ever write to. */
+const DENIED_TYPES = new Set(['password', 'hidden', 'file', 'image']);
+/** Autocomplete tokens covering credentials, payment instruments and one-time codes. */
+const DENIED_AUTOCOMPLETE = new Set([
+    'current-password', 'new-password', 'one-time-code',
+    'cc-number', 'cc-exp', 'cc-exp-month', 'cc-exp-year', 'cc-csc', 'cc-name', 'cc-type',
+]);
+/**
+ * Substrings in `name`/`id` that indicate a secret even when type/autocomplete are unset.
+ *
+ * Matched against {@link squashSeparators}'d text, so the multi-word entries catch the separator
+ * spellings people actually use. `api_key`, `api-key` and `apiKey` are all the same field; a
+ * literal-substring match sees only the last one, which is the least common of the three.
+ */
+const SUSPICIOUS_NAME = /(?:password|passwd|secret|token|csrf|xsrf|otp|cvv|cvc|ssn|creditcard|cardnumber|apikey|ccnumber|cardnum|accountnumber|routing|iban|sortcode|securitycode|passphrase|privatekey|clientsecret|accesskey|secretkey|recoverycode|backupcode|mfa)/i;
+// Deliberately NOT added as bare substrings, even though both are real PCI/banking terms
+// ("pin", "PAN" — Primary Account Number): they collide with ordinary field names once
+// separators are squashed out. `shipping` contains "pin"; `company` contains "pan". Adding
+// either here would refuse a large share of legitimate, non-sensitive fields. See
+// guards.test.ts's "does not refuse ordinary fields that happen to contain pin/pan as a
+// substring" test — it exists specifically so a future edit cannot add either back silently.
+/**
+ * Drops everything that is not a letter or digit, so separator conventions do not decide whether
+ * a guard fires. Over-matching is the safe direction here and is the point: this guard fails
+ * closed, and the cost of a false positive is a field an agent must leave to the user.
+ *
+ * Normalizes before squashing rather than after, because the naive squash used to *delete* any
+ * character outside ASCII `[a-z0-9]` instead of folding it. Deleting, not folding, is the bug:
+ * replacing one letter of a trigger word with a look-alike codepoint (fullwidth, accented, …)
+ * used to remove that letter from the squashed string entirely, so `ｐassword` (fullwidth
+ * U+FF50 `ｐ`) squashed to `assword` and matched nothing. NFKC folds that class of look-alike —
+ * fullwidth/halfwidth forms, and the Latin compatibility block — to its ordinary ASCII form
+ * before the letter can be deleted. The NFD pass afterward strips combining marks so an accented
+ * letter (`á` → `a` + combining acute) folds the same way once the mark itself is dropped.
+ *
+ * This does NOT close the general homoglyph class. NFKC has no cross-script confusables table:
+ * Cyrillic `а` (U+0430) and Greek `ο` (U+03BF) stay distinct codepoints from Latin `a`/`o` after
+ * NFKC, so `pаssword` (Cyrillic а) still squashes to something other than `password` and still
+ * bypasses `SUSPICIOUS_NAME`. Closing that would need an explicit confusables-folding table
+ * (e.g. Unicode TR39's) mapping each look-alike script's letters onto Latin before squashing —
+ * deliberately not built here; see the "known limit" test in guards.test.ts for the concrete gap.
+ */
+function squashSeparators(value) {
+    const foldedWidth = value.normalize('NFKC');
+    const withoutMarks = foldedWidth.normalize('NFD').replace(/\p{M}/gu, '');
+    return withoutMarks.replace(/[^a-z0-9]/gi, '');
+}
+/**
+ * Input types that hold no text.
+ *
+ * Writing to one succeeds mechanically and accomplishes nothing: setting `value` on a checkbox
+ * changes the string submitted *if* it is ticked, and leaves `checked` alone. The caller is told
+ * the fill worked and the box is still clear — a false success, which is worse than a refusal
+ * because it is never retried.
+ */
+const NON_TEXT_TYPES = new Set(['checkbox', 'radio', 'submit', 'reset', 'button']);
+/**
+ * Why this field's current value must not be reported back to a caller, or `null` when reading
+ * it is safe.
+ *
+ * Reading is the strictly more dangerous direction: writing into a password box gives an agent
+ * nothing, whereas reading one out hands over the secret itself. So every secrecy signal the fill
+ * guard uses applies here identically — type, autocomplete token, and a name or id that indicates
+ * a credential or anti-forgery token — and none of them may be relaxed for reads.
+ *
+ * @param field - The field's attributes.
+ * @returns The first secrecy refusal, or `null` when the value may be reported.
+ */
+export function findFieldReadRefusal(field) {
+    const type = field.type?.toLowerCase();
+    if (type !== undefined && DENIED_TYPES.has(type))
+        return 'denied-type';
+    const autocomplete = field.autocomplete?.toLowerCase();
+    if (autocomplete !== undefined) {
+        // The real grammar is space-separated tokens, but a comma-joined value
+        // (`"new-password,current-password"`) is markup an attacker-controlled page can trivially
+        // emit even though real browsers won't autofill it correctly either — splitting on
+        // whitespace alone turned the whole string into one unrecognized token, so the field still
+        // worked as a plain text input while looking unguarded.
+        for (const token of autocomplete.split(/[\s,]+/)) {
+            if (DENIED_AUTOCOMPLETE.has(token))
+                return 'denied-autocomplete';
+        }
+    }
+    if (SUSPICIOUS_NAME.test(squashSeparators(field.name ?? ''))
+        || SUSPICIOUS_NAME.test(squashSeparators(field.id ?? ''))
+        // `name`/`id` are the *machine* names; a form builder or CMS that emits `name="field_47"`
+        // next to a visible "Card number" label left the guard nothing to judge until this existed.
+        //
+        // Each label is squashed and matched on its own rather than as one joined string: squashing
+        // deletes the separators, so a join would let two innocuous labels form a trigger word across
+        // their boundary ("Address" + "Snapshot" -> "addresssnapshot", which contains "ssn"). This
+        // guard is deliberately over-inclusive, but not at the cost of matching text no page wrote.
+        || (field.accessibleLabels ?? []).some((label) => SUSPICIOUS_NAME.test(squashSeparators(label)))) {
+        return 'suspicious-name';
+    }
+    return null;
+}
+/**
+ * Why an automated fill must be refused for this field, or `null` when it is safe to write.
+ *
+ * Fails closed on anything that looks like a credential, payment instrument, one-time code, or
+ * anti-forgery token, independent of whether the field carries an agent handle. Tagging a
+ * password box does not make it fillable. Every secrecy refusal is also a fill refusal — a field
+ * whose contents an agent may not read is certainly not one it may overwrite — and two further
+ * refusals cover fields that are simply not writable.
+ *
+ * @param field - The field's attributes.
+ * @returns The first refusal reason, or `null` when the field may be filled.
+ */
+export function findFieldFillRefusal(field) {
+    const secrecy = findFieldReadRefusal(field);
+    if (secrecy !== null)
+        return secrecy;
+    const type = field.type?.toLowerCase();
+    if (type !== undefined && NON_TEXT_TYPES.has(type))
+        return 'not-text';
+    if (field.readOnly === true)
+        return 'read-only';
+    if (field.disabled === true)
+        return 'disabled';
+    return null;
+}
+const FIELD_REFUSAL_MESSAGES = {
+    'denied-type': 'this field type can never be filled by an agent',
+    'denied-autocomplete': 'this field holds a credential or payment instrument',
+    'suspicious-name': 'this field name indicates a secret or anti-forgery token',
+    'not-text': 'this control holds no text — activate it with the click verb instead of filling it',
+    'read-only': 'this field is read-only',
+    disabled: 'this field is disabled',
+};
+const FIELD_READ_REFUSAL_MESSAGES = {
+    'denied-type': 'this field type is never readable by an agent',
+    'denied-autocomplete': 'this field holds a credential or payment instrument',
+    'suspicious-name': 'this field name indicates a secret or anti-forgery token',
+};
+/** Model-readable reason for a refusal, so a blocked fill explains itself instead of failing opaquely. */
+export function describeFieldRefusal(refusal) {
+    return FIELD_REFUSAL_MESSAGES[refusal];
+}
+/** Model-readable reason a value was withheld, so a caller knows the field has contents it may not see rather than assuming it is empty. */
+export function describeFieldReadRefusal(refusal) {
+    return FIELD_READ_REFUSAL_MESSAGES[refusal];
+}
+/** Default cap on page-authored text handed to a model. */
+export const MAX_AGENT_LABEL_LENGTH = 200;
+/**
+ * C0/C1 control characters plus the Unicode bidirectional and invisible formatting ranges.
+ *
+ * The bidi overrides matter as much as the control codes: `U+202E` and friends let page text
+ * render one way and read another, which is a direct way to smuggle a different instruction
+ * into whatever reads the label back.
+ */
+const CONTROL_AND_BIDI = 
+// eslint-disable-next-line no-control-regex
+/[\u0000-\u001F\u007F-\u009F\u200B-\u200F\u202A-\u202E\u2060-\u2064\u2066-\u2069\uFEFF]/g;
+/**
+ * Normalizes page-authored text before it reaches a model.
+ *
+ * Strips control characters (including the bidirectional overrides used to make text render
+ * differently from how it reads), collapses whitespace, and caps the length. The result is still
+ * untrusted *content* — this only bounds it; it does not make it safe to follow as instruction.
+ *
+ * @param raw - Text read off the page, e.g. a `data-agent-label`.
+ * @param maxLength - Cap, defaulting to {@link MAX_AGENT_LABEL_LENGTH}.
+ * @returns The bounded text and whether anything was cut.
+ */
+export function normalizeAgentLabel(raw, maxLength = MAX_AGENT_LABEL_LENGTH) {
+    const stripped = raw.replace(CONTROL_AND_BIDI, ' ');
+    const collapsed = stripped.replace(/\s+/g, ' ').trim();
+    if (collapsed.length <= maxLength)
+        return { text: collapsed, truncated: false };
+    return { text: collapsed.slice(0, maxLength), truncated: true };
+}
+//# sourceMappingURL=guards.js.map

package/dist/core/guards.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"guards.js","sourceRoot":"","sources":["../../src/core/guards.ts"],"names":[],"mappings":"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"}

package/dist/core/handle.d.ts

@@ -0,0 +1,41 @@
+/**
+ * @module handle
+ *
+ * `agentHandle('save')` — the attribute props a component spreads onto its root element to
+ * publish itself under this package's `data-agent-*` markup convention (see
+ * `element-handles.ts`), without the caller having to know the attribute names or re-derive the
+ * handle-validity rule itself.
+ *
+ * Deliberately pure data, no DOM: this returns a plain object of string attributes, spreadable by
+ * React (`<button {...agentHandle('save')}>`), Vue, Svelte, or any renderer that accepts arbitrary
+ * attribute props on an element. That is what lets it live in this package's universal root
+ * rather than `./dom` — nothing here touches `document` or any browser global.
+ */
+import { AGENT_ELEMENT_ATTRIBUTE, AGENT_LABEL_ATTRIBUTE, AGENT_PAGE_ATTRIBUTE, AGENT_ROLE_ATTRIBUTE, type AgentElementRole } from './element-handles.js';
+/** Optional markup to attach alongside the handle itself. */
+export interface AgentHandleOptions {
+    /** What verb applies to this element — see {@link AgentElementRole}. */
+    readonly role?: AgentElementRole;
+    /** Stable, page-authored ontology for this element (e.g. `"Full name"`). Never live text. */
+    readonly label?: string;
+    /** Which published page this element belongs to, for a multi-page host. */
+    readonly page?: string;
+}
+/** The attribute props {@link agentHandle} returns, ready to spread onto an element. */
+export type AgentHandleProps = {
+    readonly [AGENT_ELEMENT_ATTRIBUTE]: string;
+} & Partial<Record<typeof AGENT_ROLE_ATTRIBUTE | typeof AGENT_LABEL_ATTRIBUTE | typeof AGENT_PAGE_ATTRIBUTE, string>>;
+/**
+ * Builds the attribute props that publish `handle` as an agent-addressable element.
+ *
+ * @param handle - The handle to publish. Must satisfy {@link isValidElementHandle} — this
+ *   function reuses that exact rule rather than a second, possibly-diverging check, since an
+ *   adversarial probe already confirmed it rejects quotes, brackets, backslashes, unicode and
+ *   overlong handles (see `element-handles.ts`).
+ * @param options - Optional role/label/page markup.
+ * @returns Attribute props to spread onto the element that should carry this handle.
+ * @throws If `handle` is not a valid element handle — never publishes a handle a caller (`page.*`
+ *   capabilities, `resolveHandleSelector`) could not later resolve.
+ */
+export declare function agentHandle(handle: string, options?: AgentHandleOptions): AgentHandleProps;
+//# sourceMappingURL=handle.d.ts.map

package/dist/core/handle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handle.d.ts","sourceRoot":"","sources":["../../src/core/handle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EACL,uBAAuB,EACvB,qBAAqB,EACrB,oBAAoB,EACpB,oBAAoB,EAEpB,KAAK,gBAAgB,EACtB,MAAM,sBAAsB,CAAC;AAE9B,6DAA6D;AAC7D,MAAM,WAAW,kBAAkB;IACjC,wEAAwE;IACxE,QAAQ,CAAC,IAAI,CAAC,EAAE,gBAAgB,CAAC;IACjC,6FAA6F;IAC7F,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,2EAA2E;IAC3E,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,wFAAwF;AACxF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,QAAQ,CAAC,CAAC,uBAAuB,CAAC,EAAE,MAAM,CAAC;CAC5C,GAAG,OAAO,CACT,MAAM,CACJ,OAAO,oBAAoB,GAAG,OAAO,qBAAqB,GAAG,OAAO,oBAAoB,EACxF,MAAM,CACP,CACF,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,GAAE,kBAAuB,GAAG,gBAAgB,CAY9F"}

package/dist/core/handle.js

@@ -0,0 +1,41 @@
+/**
+ * @module handle
+ *
+ * `agentHandle('save')` — the attribute props a component spreads onto its root element to
+ * publish itself under this package's `data-agent-*` markup convention (see
+ * `element-handles.ts`), without the caller having to know the attribute names or re-derive the
+ * handle-validity rule itself.
+ *
+ * Deliberately pure data, no DOM: this returns a plain object of string attributes, spreadable by
+ * React (`<button {...agentHandle('save')}>`), Vue, Svelte, or any renderer that accepts arbitrary
+ * attribute props on an element. That is what lets it live in this package's universal root
+ * rather than `./dom` — nothing here touches `document` or any browser global.
+ */
+import { AGENT_ELEMENT_ATTRIBUTE, AGENT_LABEL_ATTRIBUTE, AGENT_PAGE_ATTRIBUTE, AGENT_ROLE_ATTRIBUTE, isValidElementHandle, } from './element-handles.js';
+/**
+ * Builds the attribute props that publish `handle` as an agent-addressable element.
+ *
+ * @param handle - The handle to publish. Must satisfy {@link isValidElementHandle} — this
+ *   function reuses that exact rule rather than a second, possibly-diverging check, since an
+ *   adversarial probe already confirmed it rejects quotes, brackets, backslashes, unicode and
+ *   overlong handles (see `element-handles.ts`).
+ * @param options - Optional role/label/page markup.
+ * @returns Attribute props to spread onto the element that should carry this handle.
+ * @throws If `handle` is not a valid element handle — never publishes a handle a caller (`page.*`
+ *   capabilities, `resolveHandleSelector`) could not later resolve.
+ */
+export function agentHandle(handle, options = {}) {
+    if (!isValidElementHandle(handle)) {
+        throw new Error(`invalid element handle "${handle.slice(0, 128)}": `
+            + 'handles are lowercase words joined by single hyphens, and are never CSS selectors');
+    }
+    const props = { [AGENT_ELEMENT_ATTRIBUTE]: handle };
+    if (options.role !== undefined)
+        props[AGENT_ROLE_ATTRIBUTE] = options.role;
+    if (options.label !== undefined)
+        props[AGENT_LABEL_ATTRIBUTE] = options.label;
+    if (options.page !== undefined)
+        props[AGENT_PAGE_ATTRIBUTE] = options.page;
+    return props;
+}
+//# sourceMappingURL=handle.js.map

package/dist/core/handle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"handle.js","sourceRoot":"","sources":["../../src/core/handle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EACL,uBAAuB,EACvB,qBAAqB,EACrB,oBAAoB,EACpB,oBAAoB,EACpB,oBAAoB,GAErB,MAAM,sBAAsB,CAAC;AAsB9B;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,WAAW,CAAC,MAAc,EAAE,UAA8B,EAAE;IAC1E,IAAI,CAAC,oBAAoB,CAAC,MAAM,CAAC,EAAE,CAAC;QAClC,MAAM,IAAI,KAAK,CACb,2BAA2B,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,KAAK;cAClD,mFAAmF,CACtF,CAAC;IACJ,CAAC;IACD,MAAM,KAAK,GAA2B,EAAE,CAAC,uBAAuB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC5E,IAAI,OAAO,CAAC,IAAI,KAAK,SAAS;QAAE,KAAK,CAAC,oBAAoB,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAC3E,IAAI,OAAO,CAAC,KAAK,KAAK,SAAS;QAAE,KAAK,CAAC,qBAAqB,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC;IAC9E,IAAI,OAAO,CAAC,IAAI,KAAK,SAAS;QAAE,KAAK,CAAC,oBAAoB,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAC3E,OAAO,KAAyB,CAAC;AACnC,CAAC"}

package/dist/core/index.d.ts

@@ -0,0 +1,75 @@
+/**
+ * @jini-ai/agentic — the framework-free half of agent control.
+ *
+ * Everything an outside caller needs to drive a Jini frontend, with no React, no DOM, and no
+ * transport: the capability vocabulary, the two shipped manifests, the `data-agent-*` markup
+ * convention, and the refusals that must hold everywhere.
+ *
+ * Framework bindings (`@jini-ai/chat-react`, via `@jini-ai/agentic/dom`'s `createDomPageDriver`, and
+ * any Vue/Svelte sibling) import from here and add only the wiring their framework needs.
+ * Server-side hosts (an HTTP route table, an MCP stdio server) import the same manifests, so the
+ * two can never drift apart.
+ *
+ * What is deliberately NOT here: how an action reaches a page. That is a transport concern —
+ * same-document in a real site like a CMS, `postMessage` when a host embeds an untrusted
+ * preview in a sandboxed frame. The verbs are identical either way. Also not here: any product's
+ * OWN capabilities (`@jini-ai/chat-core`'s `chat.*` verbs stay in chat-core, which depends on this
+ * package for the vocabulary rather than the other way around) — see this package's
+ * source-map.md for why the split is real rather than a wholesale relocation.
+ */
+export { findCapability, findCapabilityInputError, availableCapabilities, type CapabilityDef, type CapabilityInputSchema, type CapabilityRisk, type CapabilitySurface, } from './capability.js';
+export type { PageDriver, FindElementsFilter, PageSummary } from './page-driver.js';
+export { executePageCapability, projectElementState, DEFAULT_HIGHLIGHT_MS, MAX_HIGHLIGHT_MS, MAX_STATEFUL_ELEMENTS, type FindElementsResult, type PageElementResult, type PageActivitySnapshot, type PageWriteObservation, } from './page-executor.js';
+export { PAGE_CAPABILITIES } from './page-capabilities.js';
+export { AGENT_ELEMENT_ATTRIBUTE, AGENT_ROLE_ATTRIBUTE, AGENT_LABEL_ATTRIBUTE, AGENT_PAGE_ATTRIBUTE, AGENT_ELEMENT_ROLES, isValidElementHandle, resolveHandleSelector, type AgentElementRole, type AgentElementDescriptor, type AgentElementRawState, type AgentElementState, } from './element-handles.js';
+export { agentHandle, type AgentHandleOptions, type AgentHandleProps } from './handle.js';
+export { buildAgentListHandles } from './list-handles.js';
+export { findFieldFillRefusal, findFieldReadRefusal, describeFieldRefusal, describeFieldReadRefusal, normalizeAgentLabel, MAX_AGENT_LABEL_LENGTH, type FieldDescriptor, type FieldRefusal, type FieldReadRefusal, type NormalizedLabel, } from './guards.js';
+/**
+ * Protocol adapters, named for what they derive from.
+ *
+ * Each is a ONE-WAY projection out of the neutral core: they import `capability.js`, and nothing
+ * imports back. That direction is the whole point — if the core ever imported an adapter, the
+ * protocol we happened to build against would leak into the vocabulary and the layer would stop
+ * being neutral. None of them opens a connection or touches a browser global; a framework
+ * binding owns transport and host access.
+ */
+export { toWebMcpTool, toWebMcpTools, isValidWebMcpToolName, WebMcpConfirmationRequiredError, InvalidWebMcpToolNameError, type WebMcpToolRegistration, type WebMcpToolAnnotations, type WebMcpRegisterToolOptions, type WebMcpUserInteraction, type RequestUserInteraction, type ToWebMcpToolOptions, } from './webmcp.js';
+/**
+ * Genuine AG-UI: the {@link CapabilityDef} → AG-UI *frontend tool* projection. Real conformance —
+ * it emits the protocol's own `parameters` field name (not `inputSchema`) and its canonical
+ * `TOOL_CALL_START`/`TOOL_CALL_ARGS`/`TOOL_CALL_END` event names, all three of which appear in
+ * AG-UI's published `EventType` enum.
+ */
+export { toAgUiTool, toAgUiTools, createAgUiToolResult, AG_UI_TOOL_CALL_EVENTS, type AgUiTool, type AgUiToolResultMessage, } from './ag-ui.js';
+/**
+ * Jini's **own** run-stream surface protocol, from `./gen-ui/` — six event kinds and the encoder
+ * that produces them (folded in 2026-07-26 from the standalone `@jini-ai/agui` package, plan §3a).
+ *
+ * Renamed from `./agui/` on 2026-07-27, because this is NOT AG-UI. The real Agent-User Interaction
+ * Protocol (https://github.com/ag-ui-protocol/ag-ui) carries a 33-member `SCREAMING_SNAKE` event
+ * enum — `RUN_STARTED`, `TEXT_MESSAGE_CONTENT`, `STATE_DELTA`, `STEP_STARTED`, `REASONING_*` — and
+ * shares **zero** event names with the six dotted-lowercase kinds in `./gen-ui/events.ts`, which
+ * are a de-branded port of one product's internal run-event adapter. Carrying the AG-UI name on
+ * them asserted a conformance that does not exist.
+ *
+ * `./ag-ui.ts` above was wrongly folded in with them on 2026-07-26 and moved back out on the 27th:
+ * it is the one file here that really does speak AG-UI, so merging it with these six was the exact
+ * inversion of the truth.
+ *
+ * The exported symbols were renamed `Agui`/`AGUI` → `GenUi` on 2026-07-29, finishing what the
+ * directory move started: with genuine AG-UI (`./ag-ui.ts`, exported just above as `toAgUiTool`
+ * and friends) living in the same barrel, two unrelated protocols were reading as one.
+ *
+ * `@jini-ai/http-kit` used to mount this encoder behind a route still named `/api/runs/:runId/
+ * agui-stream` — left un-renamed at the time on the assumption it was a wire contract an
+ * already-deployed client might be calling. A 2026-08-18 audit found zero callers of that route
+ * anywhere (no client in this repo or `Tovu` ever requested it, and `@jini-ai/http-kit` has never
+ * actually been published to npm, so no external integrator could depend on it either); the route,
+ * its registrar, and its tests were removed outright rather than renamed. This `gen-ui/` module
+ * itself was untouched — it is `@jini-ai/agentic`'s own public export and its removal is a separate
+ * decision.
+ */
+export { createGenUiEncoder, type GenUiEncodeContext, type GenUiEncoder, type GenUiAgentMessageEvent, type GenUiEvent, type GenUiEventBase, type GenUiEventKind, type GenUiRunLifecycleEvent, type GenUiStateUpdateEvent, type GenUiSurfaceRequestedEvent, type GenUiSurfaceRespondedEvent, type GenUiToolCallEvent, } from './gen-ui/index.js';
+export { MCP_UI_VIEW_METHODS, MCP_UI_HOST_NOTIFICATIONS, MCP_UI_VIEW_NOTIFICATIONS, MCP_UI_HOST_REQUESTS, MCP_UI_SANDBOX_NOTE, JINI_PAGE_ACTION_METHOD, JSON_RPC_ERROR_CODES, isJsonRpcMessage, isJsonRpcRequest, createJsonRpcRequest, createJsonRpcNotification, createJsonRpcResult, createJsonRpcError, createPageActionRequest, type JsonRpcMessage, type JsonRpcRequest, type JsonRpcNotification, type JsonRpcResponse, type JsonRpcError, } from './mcp-ui-apps.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/core/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,EACL,cAAc,EACd,wBAAwB,EACxB,qBAAqB,EACrB,KAAK,aAAa,EAClB,KAAK,qBAAqB,EAC1B,KAAK,cAAc,EACnB,KAAK,iBAAiB,GACvB,MAAM,iBAAiB,CAAC;AAEzB,YAAY,EAAE,UAAU,EAAE,kBAAkB,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEpF,OAAO,EACL,qBAAqB,EACrB,mBAAmB,EACnB,oBAAoB,EACpB,gBAAgB,EAChB,qBAAqB,EACrB,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACtB,KAAK,oBAAoB,EACzB,KAAK,oBAAoB,GAC1B,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAE3D,OAAO,EACL,uBAAuB,EACvB,oBAAoB,EACpB,qBAAqB,EACrB,oBAAoB,EACpB,mBAAmB,EACnB,oBAAoB,EACpB,qBAAqB,EACrB,KAAK,gBAAgB,EACrB,KAAK,sBAAsB,EAC3B,KAAK,oBAAoB,EACzB,KAAK,iBAAiB,GACvB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAAE,WAAW,EAAE,KAAK,kBAAkB,EAAE,KAAK,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAE1F,OAAO,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAE1D,OAAO,EACL,oBAAoB,EACpB,oBAAoB,EACpB,oBAAoB,EACpB,wBAAwB,EACxB,mBAAmB,EACnB,sBAAsB,EACtB,KAAK,eAAe,EACpB,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACrB,KAAK,eAAe,GACrB,MAAM,aAAa,CAAC;AAErB;;;;;;;;GAQG;AACH,OAAO,EACL,YAAY,EACZ,aAAa,EACb,qBAAqB,EACrB,+BAA+B,EAC/B,0BAA0B,EAC1B,KAAK,sBAAsB,EAC3B,KAAK,qBAAqB,EAC1B,KAAK,yBAAyB,EAC9B,KAAK,qBAAqB,EAC1B,KAAK,sBAAsB,EAC3B,KAAK,mBAAmB,GACzB,MAAM,aAAa,CAAC;AAErB;;;;;GAKG;AACH,OAAO,EACL,UAAU,EACV,WAAW,EACX,oBAAoB,EACpB,sBAAsB,EACtB,KAAK,QAAQ,EACb,KAAK,qBAAqB,GAC3B,MAAM,YAAY,CAAC;AAEpB;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,OAAO,EACL,kBAAkB,EAClB,KAAK,kBAAkB,EACvB,KAAK,YAAY,EACjB,KAAK,sBAAsB,EAC3B,KAAK,UAAU,EACf,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,sBAAsB,EAC3B,KAAK,qBAAqB,EAC1B,KAAK,0BAA0B,EAC/B,KAAK,0BAA0B,EAC/B,KAAK,kBAAkB,GACxB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,mBAAmB,EACnB,yBAAyB,EACzB,yBAAyB,EACzB,oBAAoB,EACpB,mBAAmB,EACnB,uBAAuB,EACvB,oBAAoB,EACpB,gBAAgB,EAChB,gBAAgB,EAChB,oBAAoB,EACpB,yBAAyB,EACzB,mBAAmB,EACnB,kBAAkB,EAClB,uBAAuB,EACvB,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,mBAAmB,EACxB,KAAK,eAAe,EACpB,KAAK,YAAY,GAClB,MAAM,kBAAkB,CAAC"}

package/dist/core/index.js

@@ -0,0 +1,74 @@
+/**
+ * @jini-ai/agentic — the framework-free half of agent control.
+ *
+ * Everything an outside caller needs to drive a Jini frontend, with no React, no DOM, and no
+ * transport: the capability vocabulary, the two shipped manifests, the `data-agent-*` markup
+ * convention, and the refusals that must hold everywhere.
+ *
+ * Framework bindings (`@jini-ai/chat-react`, via `@jini-ai/agentic/dom`'s `createDomPageDriver`, and
+ * any Vue/Svelte sibling) import from here and add only the wiring their framework needs.
+ * Server-side hosts (an HTTP route table, an MCP stdio server) import the same manifests, so the
+ * two can never drift apart.
+ *
+ * What is deliberately NOT here: how an action reaches a page. That is a transport concern —
+ * same-document in a real site like a CMS, `postMessage` when a host embeds an untrusted
+ * preview in a sandboxed frame. The verbs are identical either way. Also not here: any product's
+ * OWN capabilities (`@jini-ai/chat-core`'s `chat.*` verbs stay in chat-core, which depends on this
+ * package for the vocabulary rather than the other way around) — see this package's
+ * source-map.md for why the split is real rather than a wholesale relocation.
+ */
+export { findCapability, findCapabilityInputError, availableCapabilities, } from './capability.js';
+export { executePageCapability, projectElementState, DEFAULT_HIGHLIGHT_MS, MAX_HIGHLIGHT_MS, MAX_STATEFUL_ELEMENTS, } from './page-executor.js';
+export { PAGE_CAPABILITIES } from './page-capabilities.js';
+export { AGENT_ELEMENT_ATTRIBUTE, AGENT_ROLE_ATTRIBUTE, AGENT_LABEL_ATTRIBUTE, AGENT_PAGE_ATTRIBUTE, AGENT_ELEMENT_ROLES, isValidElementHandle, resolveHandleSelector, } from './element-handles.js';
+export { agentHandle } from './handle.js';
+export { buildAgentListHandles } from './list-handles.js';
+export { findFieldFillRefusal, findFieldReadRefusal, describeFieldRefusal, describeFieldReadRefusal, normalizeAgentLabel, MAX_AGENT_LABEL_LENGTH, } from './guards.js';
+/**
+ * Protocol adapters, named for what they derive from.
+ *
+ * Each is a ONE-WAY projection out of the neutral core: they import `capability.js`, and nothing
+ * imports back. That direction is the whole point — if the core ever imported an adapter, the
+ * protocol we happened to build against would leak into the vocabulary and the layer would stop
+ * being neutral. None of them opens a connection or touches a browser global; a framework
+ * binding owns transport and host access.
+ */
+export { toWebMcpTool, toWebMcpTools, isValidWebMcpToolName, WebMcpConfirmationRequiredError, InvalidWebMcpToolNameError, } from './webmcp.js';
+/**
+ * Genuine AG-UI: the {@link CapabilityDef} → AG-UI *frontend tool* projection. Real conformance —
+ * it emits the protocol's own `parameters` field name (not `inputSchema`) and its canonical
+ * `TOOL_CALL_START`/`TOOL_CALL_ARGS`/`TOOL_CALL_END` event names, all three of which appear in
+ * AG-UI's published `EventType` enum.
+ */
+export { toAgUiTool, toAgUiTools, createAgUiToolResult, AG_UI_TOOL_CALL_EVENTS, } from './ag-ui.js';
+/**
+ * Jini's **own** run-stream surface protocol, from `./gen-ui/` — six event kinds and the encoder
+ * that produces them (folded in 2026-07-26 from the standalone `@jini-ai/agui` package, plan §3a).
+ *
+ * Renamed from `./agui/` on 2026-07-27, because this is NOT AG-UI. The real Agent-User Interaction
+ * Protocol (https://github.com/ag-ui-protocol/ag-ui) carries a 33-member `SCREAMING_SNAKE` event
+ * enum — `RUN_STARTED`, `TEXT_MESSAGE_CONTENT`, `STATE_DELTA`, `STEP_STARTED`, `REASONING_*` — and
+ * shares **zero** event names with the six dotted-lowercase kinds in `./gen-ui/events.ts`, which
+ * are a de-branded port of one product's internal run-event adapter. Carrying the AG-UI name on
+ * them asserted a conformance that does not exist.
+ *
+ * `./ag-ui.ts` above was wrongly folded in with them on 2026-07-26 and moved back out on the 27th:
+ * it is the one file here that really does speak AG-UI, so merging it with these six was the exact
+ * inversion of the truth.
+ *
+ * The exported symbols were renamed `Agui`/`AGUI` → `GenUi` on 2026-07-29, finishing what the
+ * directory move started: with genuine AG-UI (`./ag-ui.ts`, exported just above as `toAgUiTool`
+ * and friends) living in the same barrel, two unrelated protocols were reading as one.
+ *
+ * `@jini-ai/http-kit` used to mount this encoder behind a route still named `/api/runs/:runId/
+ * agui-stream` — left un-renamed at the time on the assumption it was a wire contract an
+ * already-deployed client might be calling. A 2026-08-18 audit found zero callers of that route
+ * anywhere (no client in this repo or `Tovu` ever requested it, and `@jini-ai/http-kit` has never
+ * actually been published to npm, so no external integrator could depend on it either); the route,
+ * its registrar, and its tests were removed outright rather than renamed. This `gen-ui/` module
+ * itself was untouched — it is `@jini-ai/agentic`'s own public export and its removal is a separate
+ * decision.
+ */
+export { createGenUiEncoder, } from './gen-ui/index.js';
+export { MCP_UI_VIEW_METHODS, MCP_UI_HOST_NOTIFICATIONS, MCP_UI_VIEW_NOTIFICATIONS, MCP_UI_HOST_REQUESTS, MCP_UI_SANDBOX_NOTE, JINI_PAGE_ACTION_METHOD, JSON_RPC_ERROR_CODES, isJsonRpcMessage, isJsonRpcRequest, createJsonRpcRequest, createJsonRpcNotification, createJsonRpcResult, createJsonRpcError, createPageActionRequest, } from './mcp-ui-apps.js';
+//# sourceMappingURL=index.js.map

package/dist/core/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,EACL,cAAc,EACd,wBAAwB,EACxB,qBAAqB,GAKtB,MAAM,iBAAiB,CAAC;AAIzB,OAAO,EACL,qBAAqB,EACrB,mBAAmB,EACnB,oBAAoB,EACpB,gBAAgB,EAChB,qBAAqB,GAKtB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAE3D,OAAO,EACL,uBAAuB,EACvB,oBAAoB,EACpB,qBAAqB,EACrB,oBAAoB,EACpB,mBAAmB,EACnB,oBAAoB,EACpB,qBAAqB,GAKtB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAAE,WAAW,EAAkD,MAAM,aAAa,CAAC;AAE1F,OAAO,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAE1D,OAAO,EACL,oBAAoB,EACpB,oBAAoB,EACpB,oBAAoB,EACpB,wBAAwB,EACxB,mBAAmB,EACnB,sBAAsB,GAKvB,MAAM,aAAa,CAAC;AAErB;;;;;;;;GAQG;AACH,OAAO,EACL,YAAY,EACZ,aAAa,EACb,qBAAqB,EACrB,+BAA+B,EAC/B,0BAA0B,GAO3B,MAAM,aAAa,CAAC;AAErB;;;;;GAKG;AACH,OAAO,EACL,UAAU,EACV,WAAW,EACX,oBAAoB,EACpB,sBAAsB,GAGvB,MAAM,YAAY,CAAC;AAEpB;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,OAAO,EACL,kBAAkB,GAYnB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,mBAAmB,EACnB,yBAAyB,EACzB,yBAAyB,EACzB,oBAAoB,EACpB,mBAAmB,EACnB,uBAAuB,EACvB,oBAAoB,EACpB,gBAAgB,EAChB,gBAAgB,EAChB,oBAAoB,EACpB,yBAAyB,EACzB,mBAAmB,EACnB,kBAAkB,EAClB,uBAAuB,GAMxB,MAAM,kBAAkB,CAAC"}

package/dist/core/list-handles.d.ts

@@ -0,0 +1,43 @@
+/**
+ * @module list-handles
+ *
+ * How a host turns one namespace prefix (its own `agentHandle` base, e.g. `"mcp-server"`) plus a
+ * list of items' own stable ids into a distinct, stable base handle per item — the shape every
+ * repeated-row/repeated-card list needs, and that a per-host reimplementation risks getting
+ * subtly wrong (see {@link buildAgentListHandles}'s own doc for the exact failure mode).
+ *
+ * The core problem: a `data-agent-element` handle is `[a-z0-9]+(-[a-z0-9]+)*` only (see
+ * `element-handles.ts`), but the ids driving a real list (a form field's `id`, a content type's
+ * `key`, a database row's numeric id, a configured source's own id, ...) are arbitrary strings.
+ * Two different ids can also slugify to the SAME handle. Both are resolved here, once, so every
+ * list surface in every host derives its handles the same way instead of each re-deriving (and
+ * possibly getting wrong) the same two rules. Lives at this package's universal root — like
+ * `handle.ts` and `element-handles.ts` — because it is pure data with no DOM or framework
+ * involved, so any host (React, Vue, a server-rendered list) can use it identically.
+ */
+/**
+ * Builds one distinct, stable base handle per id, positionally aligned with `ids`.
+ *
+ * Handles are derived from each id's own slug, not its position in the list — an agent reading
+ * `page.find_elements` should see `<prefix>-about-us`, not `<prefix>-3`, so the same control keeps
+ * the same handle even if rows are later reordered or filtered. An id with nothing sluggable left
+ * in it (e.g. `"***"`) falls back to its 1-based position instead, so it still produces a
+ * resolvable handle rather than an empty one.
+ *
+ * Uniqueness is enforced with a suffix SEARCH, not a single `-<index>` append: appending the index
+ * alone is not collision-proof (`["x", "x-3", "x"]` would give the third entry the fallback
+ * `<prefix>-x-3`, which the second entry already holds). A duplicate handle does not fail loudly —
+ * it makes `page.click`/`page.fill` silently resolve to whichever element the DOM reaches first —
+ * so this loop is the load-bearing part of the function, not a stylistic choice.
+ *
+ * @param prefix - The list's own handle namespace (e.g. `"mcp-server"`, `"form-field"`). Must
+ *   already be a valid, non-empty handle segment — callers own that, same as every other
+ *   `agentHandle()` base.
+ * @param ids - The list items' own stable ids, in the order they are rendered.
+ * @returns One base handle per id, positionally aligned with `ids`, all distinct.
+ * @complexity Time O(n) typical, O(n²) worst case when every id slugifies identically (the suffix
+ * search then walks the full used-set for each collision); n is a list's row/card count, which is
+ * operator- or user-authored content and stays small in practice. Space O(n).
+ */
+export declare function buildAgentListHandles(prefix: string, ids: readonly string[]): string[];
+//# sourceMappingURL=list-handles.d.ts.map

package/dist/core/list-handles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"list-handles.d.ts","sourceRoot":"","sources":["../../src/core/list-handles.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,EAAE,CActF"}