@sema-agent/client-core 0.90.0 → 0.92.0

package/dist/humanTurn.d.ts

@@ -0,0 +1,91 @@
+import type { ImageInput } from './imagesWireCaps.js';
+import type { ImageVision } from './liveModelCatalog.js';
+import { type UserAttachmentDescriptor } from './userAttachmentEnvelope.js';
+export interface HumanTurnRider {
+    readonly uuid: string;
+    readonly role: 'image_meta' | 'attachment' | 'skill_body' | (string & {});
+    readonly textIncluded: boolean;
+}
+export interface HumanTurnMissing {
+    readonly kind: 'rider_text' | 'image' | 'attachment_ref' | 'non_text';
+    readonly ref?: string;
+    readonly reason: 'not_persisted' | 'not_found' | 'non_text_filtered' | 'projection_failed';
+}
+export interface HumanTurnAttachment {
+    readonly uuid: string;
+    readonly descriptor: Exclude<UserAttachmentDescriptor, {
+        kind: 'image';
+    }> | Omit<Extract<UserAttachmentDescriptor, {
+        kind: 'image';
+    }>, 'delivery'>;
+    readonly pixels?: {
+        readonly data: string;
+        readonly mimeType: string;
+    };
+}
+export interface HumanTurnItem {
+    readonly uuid: string;
+    readonly text: string;
+    readonly images?: readonly ImageInput[];
+    readonly attachments?: readonly HumanTurnAttachment[];
+    readonly attachmentIds?: readonly string[];
+    readonly riders?: readonly HumanTurnRider[];
+    readonly missing?: readonly HumanTurnMissing[];
+}
+export interface HumanTurnCaps {
+    readonly vision?: ImageVision;
+}
+export interface HumanTurnInput {
+    readonly items: readonly HumanTurnItem[];
+    readonly lane: 'objective' | 'steer';
+    readonly caps: HumanTurnCaps;
+    readonly otherBodyBytes?: number;
+}
+type EncoderShortfall = 'body_budget' | 'steer_admission' | 'vision_no' | 'vision_unknown' | 'image_too_large' | 'seat_count' | 'seat_total' | 'lane_has_no_image_seat' | 'lane_has_no_attachment_id_seat';
+export interface HumanTurnSharePart {
+    readonly kind: 'text' | 'image' | 'attachment_ref' | 'attachment_id' | 'rider_text' | 'non_text';
+    readonly ref?: string | number;
+    readonly status: 'full' | 'none';
+    readonly why?: EncoderShortfall | 'text_not_included' | HumanTurnMissing['reason'];
+}
+export interface HumanTurnShare {
+    readonly uuid: string;
+    readonly riderUuids: readonly string[];
+    readonly level: 'full' | 'partial' | 'none';
+    readonly parts: readonly HumanTurnSharePart[];
+}
+export interface HumanTurnDegraded {
+    readonly uuid: string;
+    readonly kind: HumanTurnSharePart['kind'];
+    readonly ref?: string | number;
+    readonly why: EncoderShortfall;
+}
+export type HumanTurnEncoding = {
+    readonly ok: true;
+    readonly lane: 'objective';
+    readonly text: string;
+    readonly images: readonly ImageInput[];
+    readonly attachmentIds: readonly string[];
+    readonly shares: readonly HumanTurnShare[];
+    readonly degraded: readonly HumanTurnDegraded[];
+} | {
+    readonly ok: true;
+    readonly lane: 'steer';
+    readonly text: string;
+    readonly shares: readonly HumanTurnShare[];
+    readonly degraded: readonly HumanTurnDegraded[];
+} | {
+    readonly ok: false;
+    readonly reason: 'steer_hold';
+    readonly why: 'no_text' | 'reminder_tag' | 'control_char' | 'too_long';
+} | {
+    readonly ok: false;
+    readonly reason: 'empty' | 'malformed_input' | 'malformed_item' | 'duplicate_uuid' | 'rider_collides_primary' | 'oversize';
+};
+export interface HumanTurnDelivered {
+    readonly full: readonly string[];
+    readonly partial: readonly string[];
+}
+export declare function encodeHumanTurn(input: HumanTurnInput): HumanTurnEncoding;
+export declare function deliveredUuidsOf(encoding: HumanTurnEncoding): HumanTurnDelivered;
+export {};

package/dist/humanTurn.js

@@ -0,0 +1,252 @@
+import { CORE_MAX_PENDING_STEER_CHARS, CORE_MCP_IMAGE_MAX_BASE64 } from './generated/engineFactTables.js';
+import { mintEnvelopeOf, mintReferenceOf } from './userAttachmentEnvelope.js';
+import { readEncodingShares, readHumanTurnInput } from './humanTurnRead.js';
+const REQUEST_BODY_MAX_BYTES = 8 * 1024 * 1024;
+const IMAGE_SEAT_MAX_COUNT = 20;
+const IMAGE_SEAT_MAX_BASE64_CHARS_TOTAL = 6 * 1024 * 1024;
+const STEER_REMINDER_TAG = /<\s*\/?\s*system-reminder(?:\s[^>]*)?>/i;
+const STEER_CONTROL_CHARS = /[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/;
+function utf8Length(s) {
+    let n = 0;
+    for (let i = 0; i < s.length; i += 1) {
+        const c = s.charCodeAt(i);
+        if (c < 0x80)
+            n += 1;
+        else if (c < 0x800)
+            n += 2;
+        else if (c >= 0xd800 && c <= 0xdbff && i + 1 < s.length) {
+            const d = s.charCodeAt(i + 1);
+            if (d >= 0xdc00 && d <= 0xdfff) {
+                n += 4;
+                i += 1;
+            }
+            else
+                n += 3;
+        }
+        else
+            n += 3;
+    }
+    return n;
+}
+const jsonBytes = (v) => utf8Length(JSON.stringify(v));
+function bodyBytes(other, objective, images, ids) {
+    const keys = [jsonBytes('objective') + 1 + jsonBytes(objective)];
+    if (images.length > 0)
+        keys.push(jsonBytes('images') + 1 + jsonBytes(images));
+    if (ids.length > 0)
+        keys.push(jsonBytes('attachmentIds') + 1 + jsonBytes(ids));
+    const commas = other === 2 ? keys.length - 1 : keys.length;
+    return other + keys.reduce((a, b) => a + b, 0) + commas;
+}
+function steerRefusal(text) {
+    if (text.length === 0)
+        return 'no_text';
+    if (STEER_REMINDER_TAG.test(text))
+        return 'reminder_tag';
+    if (STEER_CONTROL_CHARS.test(text))
+        return 'control_char';
+    if (text.length > CORE_MAX_PENDING_STEER_CHARS)
+        return 'too_long';
+    return undefined;
+}
+function textOf(p) {
+    if (p.form === 'reference')
+        return mintReferenceOf(p.a.d);
+    return mintEnvelopeOf(p.a.d, p.seated ? 'attached' : 'not-attached');
+}
+function compose(items, placements) {
+    const perItem = items.map((it, i) => [...placements.filter((p) => p.item === i).map(textOf), it.text].filter((s) => s.length > 0).join('\n\n'));
+    return perItem.filter((s) => s.length > 0).join('\n');
+}
+function seatedImages(items, pastedWhy, placements) {
+    const out = [];
+    items.forEach((it, i) => {
+        it.images.forEach((img, k) => {
+            if (pastedWhy[i]?.[k] === undefined)
+                out.push('url' in img ? { url: img.url } : { data: img.data, mimeType: img.mimeType });
+        });
+        for (const p of placements) {
+            if (p.item === i && p.form === 'content' && p.seated && p.a.pixels !== undefined)
+                out.push({ data: p.a.pixels.data, mimeType: p.a.pixels.mimeType });
+        }
+    });
+    return out;
+}
+const ENCODER_WHY_LIST = [
+    'body_budget',
+    'steer_admission',
+    'vision_no',
+    'vision_unknown',
+    'image_too_large',
+    'seat_count',
+    'seat_total',
+    'lane_has_no_image_seat',
+    'lane_has_no_attachment_id_seat',
+];
+const encoderWhysExhaustive = true;
+void encoderWhysExhaustive;
+const ENCODER_WHYS = new Set(ENCODER_WHY_LIST);
+function records(lane, items, pastedWhy, placements) {
+    const recs = [];
+    const push = (item, part) => {
+        recs.push({ item, part });
+    };
+    items.forEach((it, i) => {
+        if (it.text.length > 0)
+            push(i, { kind: 'text', status: 'full' });
+        it.images.forEach((_, k) => {
+            const why = pastedWhy[i]?.[k];
+            push(i, lane !== 'objective' ? { kind: 'image', ref: k, status: 'none', why: 'lane_has_no_image_seat' } : why === undefined ? { kind: 'image', ref: k, status: 'full' } : { kind: 'image', ref: k, status: 'none', why });
+        });
+        for (const p of placements) {
+            if (p.item !== i)
+                continue;
+            push(i, p.form === 'content' ? { kind: 'attachment_ref', ref: p.a.uuid, status: 'full' } : { kind: 'attachment_ref', ref: p.a.uuid, status: 'none', why: lane === 'objective' ? 'body_budget' : 'steer_admission' });
+            if (p.a.pixels !== undefined) {
+                if (lane === 'steer')
+                    push(i, { kind: 'image', ref: p.a.uuid, status: 'none', why: 'lane_has_no_image_seat' });
+                else if (p.seated && p.form === 'content')
+                    push(i, { kind: 'image', ref: p.a.uuid, status: 'full' });
+                else
+                    push(i, { kind: 'image', ref: p.a.uuid, status: 'none', why: p.seated ? 'body_budget' : p.seatWhy });
+            }
+        }
+        for (const id of it.attachmentIds) {
+            push(i, lane === 'objective' ? { kind: 'attachment_id', ref: id, status: 'full' } : { kind: 'attachment_id', ref: id, status: 'none', why: 'lane_has_no_attachment_id_seat' });
+        }
+        for (const r of it.riders) {
+            if (r.role === 'image_meta')
+                continue;
+            push(i, r.textIncluded ? { kind: 'rider_text', ref: r.uuid, status: 'full' } : { kind: 'rider_text', ref: r.uuid, status: 'none', why: 'text_not_included' });
+        }
+        for (const m of it.missing) {
+            push(i, m.ref === undefined ? { kind: m.kind, status: 'none', why: m.reason } : { kind: m.kind, ref: m.ref, status: 'none', why: m.reason });
+        }
+    });
+    return recs;
+}
+function sharesAndDegraded(items, recs) {
+    const shares = items.map((it, i) => {
+        const parts = recs.filter((r) => r.item === i).map((r) => r.part);
+        const full = parts.filter((p) => p.status === 'full').length;
+        const level = parts.length > 0 && full === parts.length ? 'full' : full === 0 ? 'none' : 'partial';
+        return { uuid: it.uuid, riderUuids: [...it.riders.map((r) => r.uuid), ...it.attachments.map((a) => a.uuid)], level, parts };
+    });
+    const degraded = [];
+    for (const r of recs) {
+        const w = r.part.why;
+        if (r.part.status === 'none' && w !== undefined && ENCODER_WHYS.has(w)) {
+            const uuid = items[r.item].uuid;
+            degraded.push(r.part.ref === undefined ? { uuid, kind: r.part.kind, why: w } : { uuid, kind: r.part.kind, ref: r.part.ref, why: w });
+        }
+    }
+    return { shares, degraded };
+}
+function encodeObjective(v) {
+    const { items } = v;
+    let count = 0;
+    let total = 0;
+    const seat = (len) => {
+        if (len > CORE_MCP_IMAGE_MAX_BASE64)
+            return 'image_too_large';
+        if (count + 1 > IMAGE_SEAT_MAX_COUNT)
+            return 'seat_count';
+        if (total + len > IMAGE_SEAT_MAX_BASE64_CHARS_TOTAL)
+            return 'seat_total';
+        count += 1;
+        total += len;
+        return undefined;
+    };
+    const pastedWhy = items.map((it) => it.images.map((img) => seat('data' in img ? img.data.length : 0)));
+    const placements = [];
+    items.forEach((it, i) => {
+        for (const a of it.attachments) {
+            const p = { item: i, a, form: 'content', seated: false, seatWhy: undefined };
+            if (a.pixels !== undefined) {
+                if (v.vision !== 'yes')
+                    p.seatWhy = v.vision === 'no' ? 'vision_no' : 'vision_unknown';
+                else {
+                    p.seatWhy = seat(a.pixels.data.length);
+                    p.seated = p.seatWhy === undefined;
+                }
+            }
+            placements.push(p);
+        }
+    });
+    const ids = items.flatMap((it) => it.attachmentIds);
+    for (;;) {
+        const text = compose(items, placements);
+        const images = seatedImages(items, pastedWhy, placements);
+        if (bodyBytes(v.otherBodyBytes, text, images, ids) <= REQUEST_BODY_MAX_BYTES) {
+            if (text.trim() === '')
+                return { ok: false, reason: 'empty' };
+            const { shares, degraded } = sharesAndDegraded(items, records('objective', items, pastedWhy, placements));
+            return { ok: true, lane: 'objective', text, images, attachmentIds: [...ids], shares, degraded };
+        }
+        let pick = -1;
+        let pickCost = -1;
+        placements.forEach((p, k) => {
+            if (p.form !== 'content')
+                return;
+            const cost = jsonBytes(textOf(p)) + (p.seated && p.a.pixels !== undefined ? jsonBytes({ data: p.a.pixels.data, mimeType: p.a.pixels.mimeType }) : 0);
+            if (cost >= pickCost) {
+                pick = k;
+                pickCost = cost;
+            }
+        });
+        if (pick < 0)
+            return { ok: false, reason: 'oversize' };
+        placements[pick].form = 'reference';
+    }
+}
+function encodeSteer(v) {
+    const { items } = v;
+    const placements = [];
+    items.forEach((it, i) => {
+        for (const a of it.attachments)
+            placements.push({ item: i, a, form: 'content', seated: false, seatWhy: undefined });
+    });
+    let text = compose(items, placements);
+    let refusal = steerRefusal(text);
+    if (refusal !== undefined && refusal !== 'no_text' && placements.length > 0) {
+        for (const p of placements)
+            p.form = 'reference';
+        text = compose(items, placements);
+        refusal = steerRefusal(text);
+    }
+    if (refusal !== undefined)
+        return { ok: false, reason: 'steer_hold', why: refusal };
+    const { shares, degraded } = sharesAndDegraded(items, records('steer', items, [], placements));
+    return { ok: true, lane: 'steer', text, shares, degraded };
+}
+export function encodeHumanTurn(input) {
+    let v;
+    try {
+        v = readHumanTurnInput(input);
+    }
+    catch {
+        return { ok: false, reason: 'malformed_input' };
+    }
+    if ('reject' in v)
+        return { ok: false, reason: v.reject };
+    try {
+        return v.lane === 'objective' ? encodeObjective(v) : encodeSteer(v);
+    }
+    catch {
+        return { ok: false, reason: 'malformed_input' };
+    }
+}
+export function deliveredUuidsOf(encoding) {
+    const shares = readEncodingShares(encoding);
+    const full = [];
+    const partial = [];
+    for (const s of shares ?? []) {
+        const into = s.level === 'full' ? full : s.level === 'partial' ? partial : undefined;
+        if (into === undefined)
+            continue;
+        into.push(s.uuid);
+        for (const r of s.riderUuids)
+            into.push(r);
+    }
+    return { full, partial };
+}

package/dist/humanTurnRead.d.ts

@@ -0,0 +1,105 @@
+import type { ImageInput } from './imagesWireCaps.js';
+import type { UserAttachmentDescriptor, UserAttachmentNotIncludedReason, UserAttachmentSource } from './userAttachmentEnvelope.js';
+import type { HumanTurnAttachment, HumanTurnEncoding, HumanTurnInput, HumanTurnMissing } from './humanTurn.js';
+import type { ImageVision } from './liveModelCatalog.js';
+export interface CellView {
+    cellType: string | undefined;
+    source: string | undefined;
+    cellId: string | undefined;
+    language: string | undefined;
+    outputs: {
+        text: string | undefined;
+        hasImage: boolean;
+    }[];
+    outputsTooLarge: boolean;
+}
+export type DescriptorView = {
+    kind: 'text';
+    source: UserAttachmentSource;
+    name: string;
+    path: string;
+    lines: string[];
+    startLine: number;
+    totalLines: number;
+    complete: boolean;
+} | {
+    kind: 'notebook';
+    source: UserAttachmentSource;
+    name: string;
+    path: string;
+    cells: CellView[];
+} | {
+    kind: 'image';
+    source: UserAttachmentSource;
+    name: string;
+    path: string;
+    sizeBytes: number | null;
+    delivery: 'attached' | 'not-attached' | undefined;
+} | {
+    kind: 'pdf';
+    source: UserAttachmentSource;
+    name: string;
+    path: string;
+    sizeBytes: number | null;
+    pageCount: number | null;
+} | {
+    kind: 'directory';
+    name: string;
+    path: string;
+    entries: string[];
+    totalEntries: number;
+} | {
+    kind: 'not-included';
+    target: 'file' | 'directory' | 'path';
+    name: string;
+    path: string;
+    sizeBytes: number | null;
+    reason: UserAttachmentNotIncludedReason;
+};
+export declare function readDescriptor(x: UserAttachmentDescriptor | HumanTurnAttachment['descriptor'], imageDelivery: 'required' | 'ignored'): DescriptorView | undefined;
+type Reason = Exclude<Extract<HumanTurnEncoding, {
+    ok: false;
+}>['reason'], 'steer_hold' | 'oversize'>;
+export interface AttachmentView {
+    uuid: string;
+    d: DescriptorView;
+    pixels: {
+        data: string;
+        mimeType: string;
+    } | undefined;
+}
+export interface RiderView {
+    uuid: string;
+    role: string;
+    textIncluded: boolean;
+}
+export interface MissingView {
+    kind: HumanTurnMissing['kind'];
+    ref: string | undefined;
+    reason: HumanTurnMissing['reason'];
+}
+export interface ItemView {
+    uuid: string;
+    text: string;
+    images: ImageInput[];
+    attachments: AttachmentView[];
+    attachmentIds: string[];
+    riders: RiderView[];
+    missing: MissingView[];
+}
+export interface InputView {
+    lane: 'objective' | 'steer';
+    vision: ImageVision;
+    otherBodyBytes: number;
+    items: ItemView[];
+}
+export declare function readHumanTurnInput(input: HumanTurnInput): InputView | {
+    readonly reject: Reason;
+};
+export interface ShareView {
+    uuid: string;
+    level: 'full' | 'partial' | 'none';
+    riderUuids: string[];
+}
+export declare function readEncodingShares(encoding: HumanTurnEncoding): ShareView[] | undefined;
+export {};