@beeuni/sdk 0.1.0

package/dist/core/turns/segments/narration.js

@@ -0,0 +1,573 @@
+import { inputPath, toolKind } from '../tool-kind.js';
+import { getToolPrimaryArg, normalizeName } from '../tools/tool-meta.js';
+import { parseWebSearchOutput, wsDomain } from '../tools/web-helpers.js';
+import { stripTrailingSlashes } from '../text-scan.js';
+function safeHttpUrl(value) {
+    if (typeof value !== 'string' || !value.trim())
+        return null;
+    try {
+        const url = new URL(value.trim());
+        return url.protocol === 'http:' || url.protocol === 'https:' ? url.toString() : null;
+    }
+    catch {
+        return null;
+    }
+}
+const FAMILY_OF_KIND = {
+    read: 'explore',
+    list: 'explore',
+    glob: 'explore',
+    grep: 'explore',
+    write: 'edit',
+    edit: 'edit',
+    apply_patch: 'edit',
+    bash: 'run',
+    pty: 'run',
+    web_search: 'web',
+    webfetch: 'web',
+    media: 'create',
+    show: 'create',
+    task: 'delegate',
+    delegate: 'delegate',
+    sessions: 'sessions',
+    todowrite: 'plan',
+    question: 'ask',
+    memory: 'memory',
+    connectors: 'connectors',
+    automations: 'automations',
+    projects: 'projects',
+    skill: 'skills',
+    context: 'hidden',
+    retired: 'retired',
+    other: 'other',
+};
+export function familyForTool(toolName) {
+    return FAMILY_OF_KIND[toolKind(toolName)];
+}
+export function narrationToolName(toolName) {
+    const n = normalizeName(toolName).replace(/__+/g, '/');
+    const leaf = n.includes('/') ? n.slice(n.lastIndexOf('/') + 1) : n;
+    return leaf
+        .replace(/_/g, ' ')
+        .trim()
+        .replace(/\b\w/g, (c) => c.toUpperCase());
+}
+const CONTEXT_LABEL_BY_FAMILY = {
+    run: 'Terminal',
+    memory: 'Memory',
+};
+export function contextLabelForTool(toolName) {
+    const family = familyForTool(toolName);
+    const label = family === 'hidden' ? undefined : CONTEXT_LABEL_BY_FAMILY[family];
+    return label ?? narrationToolName(toolName);
+}
+function plural(n, one, many) {
+    return n === 1 ? one : many;
+}
+function joinWithAnd(items) {
+    if (items.length === 0)
+        return '';
+    if (items.length === 1)
+        return items[0];
+    if (items.length === 2)
+        return `${items[0]} and ${items[1]}`;
+    return `${items.slice(0, -1).join(', ')}, and ${items[items.length - 1]}`;
+}
+function firstArg(parts) {
+    return parts.length ? getToolPrimaryArg(parts[0]) : '';
+}
+function rawInput(part) {
+    const state = (part.state ?? {});
+    return state.input ?? {};
+}
+const DELEGATE_ACTION = {
+    agent_spawn: 'spawn',
+    agent_task: 'spawn',
+    agent_task_create: 'spawn',
+    agent_task_start: 'spawn',
+    task: 'spawn',
+    task_create: 'spawn',
+    task_start: 'spawn',
+    session_spawn: 'spawn',
+    session_start_background: 'spawn',
+    agent_message: 'message',
+    agent_task_message: 'message',
+    task_message: 'message',
+    session_message: 'message',
+    agent_status: 'status',
+    agent_task_list: 'status',
+    agent_task_get: 'status',
+    task_list: 'status',
+    task_get: 'status',
+    agent_stop: 'stop',
+    agent_task_cancel: 'stop',
+    task_cancel: 'stop',
+    agent_task_approve: 'done',
+    task_approve: 'done',
+    task_done: 'done',
+    task_delete: 'delete',
+};
+function delegateAction(part) {
+    const t = normalizeName(part.tool);
+    if (t === 'agent_task_update' || t === 'task_update') {
+        switch (rawInput(part).action || '') {
+            case 'start':
+                return 'spawn';
+            case 'cancel':
+                return 'stop';
+            case 'approve':
+                return 'done';
+            default:
+                return 'message';
+        }
+    }
+    return DELEGATE_ACTION[t] ?? 'message';
+}
+function classifyAutomationAction(action) {
+    switch (action) {
+        case 'create':
+            return 'create';
+        case 'update':
+            return 'update';
+        case 'delete':
+            return 'delete';
+        case 'test':
+            return 'test';
+        case 'pause':
+        case 'resume':
+            return 'control';
+        case 'list':
+        case 'get':
+            return 'read';
+        default:
+            return 'unknown';
+    }
+}
+function automationAction(part) {
+    const t = normalizeName(part.tool);
+    if (t === 'triggers') {
+        const action = rawInput(part).action || 'list';
+        return classifyAutomationAction(action);
+    }
+    const m = t.match(/^trigger_(.+)$/);
+    return classifyAutomationAction(m ? m[1] : 'list');
+}
+const CONNECTOR_ACTION = {
+    connector_setup: 'connect',
+    connector_get: 'read',
+    connector_list: 'read',
+    beeuni_connector_discover: 'read',
+    beeuni_connector_describe: 'read',
+    beeuni_connectors: 'read',
+    beeuni_connectors_connectors: 'read',
+    beeuni_connectors_discover: 'read',
+    beeuni_connectors_describe: 'read',
+    beeuni_connector_call: 'call',
+    beeuni_connectors_call: 'call',
+};
+function connectorAction(part) {
+    return CONNECTOR_ACTION[normalizeName(part.tool)] ?? 'read';
+}
+const PROJECT_ACTION = {
+    project_get: 'open',
+    project_list: 'open',
+    project_select: 'open',
+    project_update: 'update',
+    project_create: 'create',
+    project_delete: 'delete',
+};
+function projectAction(part) {
+    return PROJECT_ACTION[normalizeName(part.tool)] ?? 'open';
+}
+function allSame(items) {
+    return items.every((i) => i === items[0]);
+}
+const MEMORY_COMMAND_ACTION = {
+    view: 'read',
+    create: 'write',
+    str_replace: 'write',
+    insert: 'write',
+    rename: 'write',
+    delete: 'delete',
+};
+function memoryAction(part) {
+    const t = normalizeName(part.tool);
+    if (t !== 'memory')
+        return 'read';
+    const command = rawInput(part).command;
+    return (command && MEMORY_COMMAND_ACTION[command]) || 'unknown';
+}
+const IMAGE_GEN_ACTION_SENTENCE = {
+    generate: 'Made an image',
+    edit: 'Edited an image',
+    upscale: 'Upscaled an image',
+    remove_bg: 'Removed an image background',
+};
+const PRESENTATION_GEN_ACTION_SENTENCE = {
+    create_slide: 'Added a slide to a presentation',
+    list_slides: "Checked a presentation's slides",
+    list_presentations: 'Checked your presentations',
+    delete_slide: 'Deleted a slide from a presentation',
+    delete_presentation: 'Deleted a presentation',
+    validate_slide: 'Checked a slide',
+    export_pdf: 'Exported a presentation to PDF',
+    export_pptx: 'Exported a presentation to PPTX',
+    preview: 'Previewed a presentation',
+    serve: 'Previewed a presentation',
+};
+function basename(p) {
+    const cleaned = stripTrailingSlashes(p.replace(/\\/g, '/'));
+    const idx = cleaned.lastIndexOf('/');
+    return idx >= 0 ? cleaned.slice(idx + 1) : cleaned;
+}
+function showLabel(part) {
+    const input = rawInput(part);
+    const title = typeof input.title === 'string' ? input.title.trim() : '';
+    if (title)
+        return title;
+    const description = typeof input.description === 'string' ? input.description.trim() : '';
+    if (description)
+        return truncate(description, 60);
+    const path = typeof input.path === 'string' ? input.path : '';
+    if (path)
+        return basename(path);
+    const url = typeof input.url === 'string' ? input.url : '';
+    if (url) {
+        const safeUrl = safeHttpUrl(url);
+        return safeUrl ? wsDomain(safeUrl) : 'a link';
+    }
+    return '';
+}
+function truncate(s, max = 60) {
+    const trimmed = s.replace(/\s+/g, ' ').trim();
+    return trimmed.length > max ? trimmed.slice(0, max - 1) + '…' : trimmed;
+}
+function imageGenSentence(part) {
+    const action = rawInput(part).action;
+    return (action && IMAGE_GEN_ACTION_SENTENCE[action]) || 'Worked on an image';
+}
+function presentationGenSentence(part) {
+    const action = rawInput(part).action;
+    return (action && PRESENTATION_GEN_ACTION_SENTENCE[action]) || 'Worked on a presentation';
+}
+function createMediaOf(key) {
+    return key.slice(0, key.indexOf(':'));
+}
+const IMAGE_GEN_ACTION_KEY = {
+    generate: 'image:generate',
+    edit: 'image:edit',
+    upscale: 'image:upscale',
+    remove_bg: 'image:remove_bg',
+};
+const PRESENTATION_GEN_ACTION_KEY = {
+    create_slide: 'presentation:create_slide',
+    list_slides: 'presentation:list_slides',
+    list_presentations: 'presentation:list_presentations',
+    delete_slide: 'presentation:delete_slide',
+    delete_presentation: 'presentation:delete_presentation',
+    validate_slide: 'presentation:validate_slide',
+    export_pdf: 'presentation:export_pdf',
+    export_pptx: 'presentation:export_pptx',
+    preview: 'presentation:preview',
+    serve: 'presentation:preview',
+};
+function createPartKey(part) {
+    const t = normalizeName(part.tool);
+    if (t === 'image_gen') {
+        const action = rawInput(part).action;
+        return (action && IMAGE_GEN_ACTION_KEY[action]) || 'image:unknown';
+    }
+    if (t === 'video_gen')
+        return 'video:create';
+    if (t === 'presentation_gen') {
+        const action = rawInput(part).action;
+        return (action && PRESENTATION_GEN_ACTION_KEY[action]) || 'presentation:unknown';
+    }
+    return 'shown:result';
+}
+const PRESENTATION_GEN_ARTIFACT_ACTIONS = new Set(['create_slide', 'export_pdf', 'export_pptx']);
+export function createArtifactKind(part) {
+    const t = normalizeName(part.tool);
+    if (t === 'image_gen')
+        return 'image';
+    if (t === 'video_gen')
+        return 'video';
+    if (t === 'presentation_gen') {
+        const action = rawInput(part).action;
+        if (!action)
+            return 'presentation';
+        return PRESENTATION_GEN_ARTIFACT_ACTIONS.has(action) ? 'presentation' : null;
+    }
+    return null;
+}
+const CREATE_GROUP_SENTENCE = {
+    'image:generate': (n) => `Made ${n} images`,
+    'image:edit': (n) => `Edited ${n} images`,
+    'image:upscale': (n) => `Upscaled ${n} images`,
+    'image:remove_bg': (n) => `Removed backgrounds from ${n} images`,
+    'image:unknown': (n) => `Worked on ${n} images`,
+    'video:create': (n) => `Made ${n} videos`,
+    'presentation:create_slide': (n) => `Added ${n} slides`,
+    'presentation:delete_slide': (n) => `Deleted ${n} slides`,
+    'presentation:delete_presentation': (n) => `Deleted ${n} presentations`,
+    'presentation:list_slides': () => "Checked a presentation's slides",
+    'presentation:list_presentations': () => 'Checked your presentations',
+    'presentation:validate_slide': () => 'Checked slides',
+    'presentation:export_pdf': (n) => `Exported ${n} presentations to PDF`,
+    'presentation:export_pptx': (n) => `Exported ${n} presentations to PPTX`,
+    'presentation:preview': (n) => `Previewed ${n} presentations`,
+    'presentation:unknown': (n) => `Worked on ${n} presentations`,
+    'shown:result': (n) => `Showed you ${n} results`,
+};
+const CREATE_MEDIA_NOUN = {
+    image: 'image',
+    video: 'video',
+    presentation: 'presentation',
+    shown: 'result',
+};
+function mixedCreateSentence(keys) {
+    const counts = { image: 0, video: 0, presentation: 0, shown: 0 };
+    for (const key of keys)
+        counts[createMediaOf(key)]++;
+    const segments = [];
+    Object.keys(counts).forEach((media) => {
+        const c = counts[media];
+        if (c)
+            segments.push(`${c} ${plural(c, CREATE_MEDIA_NOUN[media], `${CREATE_MEDIA_NOUN[media]}s`)}`);
+    });
+    return `Worked on ${joinWithAnd(segments)}`;
+}
+export function narrateStep(family, parts) {
+    const n = parts.length;
+    const arg = firstArg(parts);
+    switch (family) {
+        case 'explore': {
+            const reads = parts.filter((p) => normalizeName(p.tool) === 'read').length;
+            if (reads === n)
+                return `Read ${n} ${plural(n, 'file', 'files')}`;
+            if (reads === 0)
+                return 'Looked through your files';
+            return `Looked through your files · ${reads} read`;
+        }
+        case 'edit': {
+            const files = new Set(parts.map((p) => inputPath(rawInput(p))).filter(Boolean)).size || n;
+            const verb = parts.every((p) => normalizeName(p.tool) === 'write') ? 'Wrote' : 'Updated';
+            if (files === 1)
+                return arg ? `${verb} ${arg}` : `${verb} a file`;
+            return `${verb} ${files} files`;
+        }
+        case 'run':
+            return n === 1 ? 'Ran a command' : `Ran ${n} commands`;
+        case 'web': {
+            const isSearch = (p) => {
+                const t = normalizeName(p.tool);
+                return t === 'web_search' || t === 'websearch' || t === 'image_search';
+            };
+            const searches = parts.filter(isSearch).length;
+            if (searches === n)
+                return `Searched the web · ${n} ${plural(n, 'query', 'queries')}`;
+            if (searches === 0)
+                return `Read ${n} ${plural(n, 'page', 'pages')}`;
+            const urls = new Set();
+            for (const p of parts) {
+                if (isSearch(p)) {
+                    const raw = p.state?.output;
+                    for (const src of parseWebSearchOutput(raw).flatMap((q) => q.sources)) {
+                        if (src.url)
+                            urls.add(src.url);
+                    }
+                }
+                else {
+                    const url = p.state?.input?.url;
+                    if (typeof url === 'string' && url)
+                        urls.add(url);
+                }
+            }
+            const count = urls.size || n;
+            return `Searched and read ${count} ${plural(count, 'source', 'sources')}`;
+        }
+        case 'create': {
+            if (n === 1) {
+                const p = parts[0];
+                const t = normalizeName(p.tool);
+                if (t === 'image_gen')
+                    return imageGenSentence(p);
+                if (t === 'video_gen')
+                    return 'Made a video';
+                if (t === 'presentation_gen')
+                    return presentationGenSentence(p);
+                const label = showLabel(p);
+                return label ? `Showed you ${label}` : 'Showed you the result';
+            }
+            const keys = parts.map(createPartKey);
+            if (allSame(keys))
+                return CREATE_GROUP_SENTENCE[keys[0]](n);
+            return mixedCreateSentence(keys);
+        }
+        case 'plan':
+            return n === 1 ? 'Planned the work' : `Planned the work · ${n} steps`;
+        case 'delegate': {
+            const actions = parts.map(delegateAction);
+            if (allSame(actions)) {
+                switch (actions[0]) {
+                    case 'spawn':
+                        return n === 1 ? 'Asked a helper agent' : `Worked with ${n} helper agents`;
+                    case 'message':
+                        return n === 1
+                            ? 'Sent instructions to a helper agent'
+                            : `Sent instructions to ${n} helper agents`;
+                    case 'status':
+                        return 'Checked on a helper agent';
+                    case 'stop':
+                        return n === 1 ? 'Stopped a helper agent' : `Stopped ${n} helper agents`;
+                    case 'done':
+                        return n === 1 ? 'A helper agent finished a task' : `Helper agents finished ${n} tasks`;
+                    case 'delete':
+                        return n === 1 ? 'Removed a task' : `Removed ${n} tasks`;
+                }
+            }
+            return n === 1 ? 'Worked with a helper agent' : `Worked with helper agents · ${n} steps`;
+        }
+        case 'sessions':
+            return 'Checked earlier work';
+        case 'memory': {
+            const actions = parts.map(memoryAction);
+            if (allSame(actions)) {
+                switch (actions[0]) {
+                    case 'write':
+                        return n === 1 ? 'Wrote to its memory' : `Wrote to its memory · ${n} updates`;
+                    case 'delete':
+                        return n === 1 ? 'Deleted from its memory' : `Deleted ${n} things from its memory`;
+                    case 'read':
+                        return 'Recalled what you told it before';
+                }
+            }
+            return 'Worked with its memory';
+        }
+        case 'connectors': {
+            const actions = parts.map(connectorAction);
+            if (allSame(actions)) {
+                switch (actions[0]) {
+                    case 'connect':
+                        if (n === 1)
+                            return arg ? `Connected to ${arg}` : 'Connected a connector';
+                        return `Connected ${n} connectors`;
+                    case 'call':
+                        return n === 1 ? 'Used a connector' : `Made ${n} connector calls`;
+                    case 'read':
+                        return 'Checked your connectors';
+                }
+            }
+            return 'Worked with your connectors';
+        }
+        case 'automations': {
+            const actions = parts.map(automationAction);
+            if (allSame(actions)) {
+                switch (actions[0]) {
+                    case 'create':
+                        return n === 1 ? 'Set up an automation' : `Set up ${n} automations`;
+                    case 'update':
+                        return n === 1 ? 'Updated an automation' : `Updated ${n} automations`;
+                    case 'delete':
+                        return n === 1 ? 'Deleted an automation' : `Deleted ${n} automations`;
+                    case 'control':
+                        return n === 1 ? 'Adjusted an automation' : `Adjusted ${n} automations`;
+                    case 'test':
+                        return n === 1 ? 'Tested an automation' : `Tested ${n} automations`;
+                    case 'read':
+                        return 'Checked your automations';
+                    case 'unknown':
+                        return 'Worked with your automations';
+                }
+            }
+            return 'Worked with your automations';
+        }
+        case 'projects': {
+            const actions = parts.map(projectAction);
+            if (allSame(actions)) {
+                switch (actions[0]) {
+                    case 'delete':
+                        return n === 1
+                            ? "Tried to delete a project — deletion isn't allowed"
+                            : `Tried to delete ${n} projects — deletion isn't allowed`;
+                    case 'create':
+                        if (n === 1)
+                            return arg ? `Created ${arg}` : 'Created a project';
+                        return `Created ${n} projects`;
+                    case 'update':
+                        if (n === 1)
+                            return arg ? `Updated ${arg}` : 'Updated your project';
+                        return `Updated ${n} projects`;
+                    case 'open':
+                        if (n === 1)
+                            return arg ? `Opened ${arg}` : 'Opened your project';
+                        return `Opened ${n} projects`;
+                }
+            }
+            return arg ? `Worked in ${arg}` : 'Worked in your project';
+        }
+        case 'skills': {
+            if (n === 1)
+                return arg ? `Used the ${arg} skill` : 'Used a skill';
+            return `Used ${n} skills`;
+        }
+        case 'ask':
+            return 'Asked you a question';
+        case 'retired':
+            return 'Used a connector that has since been removed';
+        case 'other': {
+            if (n === 1)
+                return `Used ${narrationToolName(parts[0].tool)}`;
+            const names = Array.from(new Set(parts.map((p) => narrationToolName(p.tool))));
+            if (names.length === 1)
+                return `Used ${names[0]} · ${n} times`;
+            return `Used ${joinWithAnd(names)}`;
+        }
+    }
+}
+export function narrateFailedStep(family, parts) {
+    const arg = firstArg(parts);
+    switch (family) {
+        case 'explore':
+            return "Couldn't read your files";
+        case 'edit': {
+            if (parts.length === 1) {
+                const verb = normalizeName(parts[0].tool) === 'write' ? 'write' : 'update';
+                return arg ? `Couldn't ${verb} ${arg}` : `Couldn't ${verb} a file`;
+            }
+            return "Couldn't update some files";
+        }
+        case 'run':
+            return 'A command failed';
+        case 'web':
+            return "Couldn't finish searching the web";
+        case 'create':
+            return "Couldn't finish making that";
+        case 'plan':
+            return "Couldn't update the plan";
+        case 'delegate':
+            return 'A helper agent hit a problem';
+        case 'sessions':
+            return "Couldn't check earlier work";
+        case 'memory':
+            return "Couldn't reach its memory";
+        case 'connectors':
+            return "Couldn't reach a connector";
+        case 'automations':
+            return 'Hit a problem with your automations';
+        case 'projects':
+            return 'Hit a problem with your project';
+        case 'skills':
+            return "Couldn't use a skill";
+        case 'ask':
+            return "Couldn't ask you a question";
+        case 'retired':
+            return 'Used a connector that has since been removed';
+        case 'other': {
+            const failed = parts.filter((p) => p.state?.status === 'error');
+            const source = failed.length ? failed : parts;
+            const names = Array.from(new Set(source.map((p) => narrationToolName(p.tool))));
+            return `Couldn't finish using ${joinWithAnd(names)}`;
+        }
+    }
+}

package/dist/core/turns/segments/segment-turn.d.ts

@@ -0,0 +1,15 @@
+import type { Part, TextPart, ToolPart } from '../../runtime/client.js';
+export type Segment = {
+    kind: 'burst';
+    parts: Part[];
+} | {
+    kind: 'text';
+    part: TextPart;
+} | {
+    kind: 'standalone';
+    part: ToolPart;
+};
+export interface SegmentTurnOptions {
+    standaloneCallIds?: ReadonlySet<string>;
+}
+export declare function segmentTurn(parts: ReadonlyArray<Part>, opts?: SegmentTurnOptions): Segment[];

package/dist/core/turns/segments/segment-turn.js

@@ -0,0 +1,32 @@
+import { isTextPart, isToolPart } from '../parts.js';
+import { isInvisibleActivityPart, isStandaloneActivityTool } from './session-activity-groups.js';
+export function segmentTurn(parts, opts = {}) {
+    const segments = [];
+    let pending = [];
+    const flush = () => {
+        if (pending.length > 0) {
+            segments.push({ kind: 'burst', parts: pending });
+            pending = [];
+        }
+    };
+    for (const part of parts) {
+        if (isInvisibleActivityPart(part))
+            continue;
+        if (isTextPart(part)) {
+            flush();
+            segments.push({ kind: 'text', part });
+            continue;
+        }
+        if (isToolPart(part)) {
+            const standalone = isStandaloneActivityTool(part.tool) || !!opts.standaloneCallIds?.has(part.callID);
+            if (standalone) {
+                flush();
+                segments.push({ kind: 'standalone', part });
+                continue;
+            }
+        }
+        pending.push(part);
+    }
+    flush();
+    return segments;
+}

package/dist/core/turns/segments/session-activity-groups.d.ts

@@ -0,0 +1,20 @@
+export declare function normalizeActivityToolName(toolName: string | undefined): string;
+export declare function isShellActivityTool(toolName: string | undefined): boolean;
+export declare function isQuestionTool(toolName: string | undefined): boolean;
+export declare function shellActivityGroupLabel(count: number, running: boolean): string;
+export declare const NO_GROUP_ACTIVITY_TOOLS: Set<string>;
+export declare function isNoGroupActivityTool(toolName: string | undefined): boolean;
+export declare function writeActivityGroupLabel(count: number, running: boolean): string;
+export declare function isInvisibleActivityPart(part: ActivityPartLike): boolean;
+export interface ActivityPartLike {
+    type?: string;
+    text?: string;
+    tool?: string;
+    state?: {
+        status?: string;
+        input?: Record<string, unknown> | null;
+    } | null;
+}
+export declare function isEmptyShowPart(part: ActivityPartLike): boolean;
+export declare const STANDALONE_TOOLS: ReadonlySet<string>;
+export declare function isStandaloneActivityTool(toolName: string | undefined): boolean;