@shardflux/cli 0.24.0 → 0.25.0

package/dist/transcribe-commands.js

@@ -0,0 +1,80 @@
+/**
+ * `shard transcribe <file>` (0.25.0+): what a recording says, with each word's time, through @shardflux/sdk's
+ * `transcriptions.transcribe()` (GET /v1/transcriptions). The signed-in session or SHARDFLUX_API_KEY, like
+ * `shard route` and `shard ask`; the audio goes to the API only and is not kept.
+ */
+import { readFile } from 'node:fs/promises';
+import { extname } from 'node:path';
+import { audioFormatOf } from '@shardflux/sdk';
+import { out, str } from "./commands.js";
+import { EXIT, UsageError } from "./errors.js";
+import { inScope } from "./router-commands.js";
+/** What one transcription holds (the API's bound; past it the rest is not transcribed and `truncated` says so). */
+export const TRANSCRIBE_MAX_BYTES = 6 * 1024 * 1024;
+const FORMATS = ['webm', 'wav', 'pcm16'];
+const BY_EXTENSION = { '.webm': 'webm', '.weba': 'webm', '.wav': 'wav', '.wave': 'wav', '.pcm': 'pcm16', '.raw': 'pcm16' };
+const SAMPLE_RATES = [8000, 16000, 22050, 24000, 32000, 44100, 48000];
+/** `12.34` seconds as `0:12.34`. */
+const clock = (s) => `${Math.floor(s / 60)}:${(s % 60).toFixed(2).padStart(5, '0')}`;
+/** The readable form: the text, then (with --words) one line per word with its start and end. */
+export function transcriptText(t, words) {
+    const lines = [t.text || '(no speech)'];
+    if (t.truncated)
+        lines.push(`(only the first ${Math.round(t.duration)} s were transcribed)`);
+    if (words)
+        for (const w of t.words)
+            lines.push(`${clock(w.start)}  ${clock(w.end)}  ${w.w}`);
+    return `${lines.join('\n')}\n`;
+}
+export const TRANSCRIBE_HANDLERS = {
+    async transcribe(ctx, values, [file]) {
+        if (!file)
+            throw new UsageError('missing <file> for "shard transcribe"');
+        const named = str(values.format);
+        if (named !== undefined && !FORMATS.includes(named))
+            throw new UsageError(`--format must be one of ${FORMATS.join(', ')}`);
+        const rateText = str(values['sample-rate']);
+        const sampleRate = rateText === undefined ? undefined : Number(rateText);
+        if (sampleRate !== undefined && !SAMPLE_RATES.includes(sampleRate))
+            throw new UsageError(`--sample-rate must be one of ${SAMPLE_RATES.join(', ')}`);
+        const language = str(values.language);
+        if (language !== undefined && !/^[a-z]{2,3}$/.test(language))
+            throw new UsageError('--language must be an ISO 639-1 code such as en or fi');
+        const bytes = await readFile(file).catch((e) => {
+            throw new UsageError(`cannot read "${file}" (${e.code === 'EISDIR' ? 'a folder' : e.code ?? e.message})`);
+        });
+        const format = named ?? audioFormatOf(bytes) ?? BY_EXTENSION[extname(file).toLowerCase()];
+        if (!format)
+            throw new UsageError(`cannot tell the audio format of "${file}"`, 'pass --format webm|wav|pcm16 (WebM/Opus, PCM WAV or raw 16-bit mono)');
+        if (format === 'pcm16' && sampleRate === undefined)
+            throw new UsageError('raw pcm16 audio needs --sample-rate (for example 16000)');
+        if (format !== 'pcm16' && sampleRate !== undefined)
+            throw new UsageError('--sample-rate is only for --format pcm16');
+        if (bytes.length > TRANSCRIBE_MAX_BYTES)
+            ctx.io.stderr.write(`Only the first ${TRANSCRIBE_MAX_BYTES / 1024 / 1024} MB (and at most 120 s) of "${file}" is transcribed.\n`);
+        const audio = bytes.subarray(0, TRANSCRIBE_MAX_BYTES);
+        try {
+            const transcript = await inScope(ctx, values, (client, scope) => client.transcriptions.transcribe(audio, {
+                format,
+                ...(sampleRate === undefined ? {} : { sampleRate }),
+                ...(language === undefined ? {} : { language }),
+                ...scope,
+                signal: ctx.signal,
+                onEvent: (e) => {
+                    if (e.type === 'queued')
+                        ctx.io.stderr.write(`Queued: position ${e.position}, about ${Math.max(1, Math.round(e.expectedWaitMs / 1000))} s\n`);
+                },
+            }));
+            if (ctx.json)
+                out(ctx, '', transcript);
+            else
+                ctx.io.stdout.write(transcriptText(transcript, values.words === true));
+            return EXIT.ok;
+        }
+        catch (err) {
+            if (ctx.signal.aborted)
+                return EXIT.interrupted;
+            throw err;
+        }
+    },
+};

package/dist/worktree-twin-engine.d.ts

@@ -119,6 +119,14 @@ export interface LoopDeps {
  * runs immediately. The first pass that succeeds after failures clears them too and runs again at once.
  */
 export declare function runTwinLoop(deps: LoopDeps, signal: AbortSignal): Promise<void>;
+/**
+ * A VM of the project that reads the project hub: an awake one reads it without waking anything; else the project's
+ * small space reader (woken). The twin lands from it when a conversation's VM is gone; `shard task land` merges there.
+ */
+export declare function projectHubCell(ctx: Ctx, projectId: string, signal?: AbortSignal, agentLabel?: string): Promise<{
+    cell: TwinCell;
+    close(): void;
+}>;
 /** The device helper's twin. Nothing here asks the user anything. */
 export declare function runWorktreeTwin(ctx: Ctx, device: string, signal: AbortSignal): Promise<void>;
 export declare const TWIN_HANDLERS: Record<string, Handler>;

package/dist/worktree-twin-engine.js

@@ -500,13 +500,36 @@ function reachable(url) {
     });
 }
 const gone = (error) => error.status === 404 || error.details?.reason === 'workspace_deleted';
+const openCell = (ws, agentLabel) => {
+    const cell = ws.cell({ agentLabel });
+    return { cell, close: () => cell.close() };
+};
+/**
+ * A VM of the project that reads the project hub: an awake one reads it without waking anything; else the project's
+ * small space reader (woken). The twin lands from it when a conversation's VM is gone; `shard task land` merges there.
+ */
+export async function projectHubCell(ctx, projectId, signal, agentLabel = 'shard-twin') {
+    const client = conversationClient(ctx);
+    const all = (await listConversations(ctx, projectId)).filter(c => !ended(c))
+        .sort((a, b) => (b.last_activity_at ?? '').localeCompare(a.last_activity_at ?? ''));
+    for (const c of all) {
+        try {
+            const ws = await client.workspaces.get(c.workspace_id);
+            if (!ws.data.deleted_at && ws.ready)
+                return openCell(ws, agentLabel);
+        }
+        catch { /* another may be awake */ }
+    }
+    const reader = await client.conversations.spaceReader(projectId, { ...(signal ? { signal } : {}) });
+    const ws = await client.workspaces.get(reader.workspace.id);
+    if (!ws.ready)
+        await ws.wake({ timeoutMs: ctx.wakeTimeoutMs, ...(signal ? { signal } : {}) });
+    return openCell(ws, agentLabel);
+}
 /** The device helper's twin. Nothing here asks the user anything. */
 export async function runWorktreeTwin(ctx, device, signal) {
     const client = () => conversationClient(ctx);
-    const open = (ws) => {
-        const cell = ws.cell({ agentLabel: 'shard-twin' });
-        return { cell, close: () => cell.close() };
-    };
+    const open = (ws) => openCell(ws, 'shard-twin');
     const engine = new TwinEngine({
         records: () => Object.values(localConversations(ctx)),
         conversations: async (projectId) => await listConversations(ctx, projectId),
@@ -539,24 +562,7 @@ export async function runWorktreeTwin(ctx, device, signal) {
                 await ws.wake({ timeoutMs: ctx.wakeTimeoutMs, signal });
             return open(ws);
         },
-        hubCell: async (projectId) => {
-            // An awake VM of the project reads the hub without waking anything; else the project's small space reader.
-            const all = (await listConversations(ctx, projectId)).filter(c => !ended(c))
-                .sort((a, b) => (b.last_activity_at ?? '').localeCompare(a.last_activity_at ?? ''));
-            for (const c of all) {
-                try {
-                    const ws = await client().workspaces.get(c.workspace_id);
-                    if (!ws.data.deleted_at && ws.ready)
-                        return open(ws);
-                }
-                catch { /* another may be awake */ }
-            }
-            const reader = await client().conversations.spaceReader(projectId, { signal });
-            const ws = await client().workspaces.get(reader.workspace.id);
-            if (!ws.ready)
-                await ws.wake({ timeoutMs: ctx.wakeTimeoutMs, signal });
-            return open(ws);
-        },
+        hubCell: projectId => projectHubCell(ctx, projectId, signal),
         resume: async (c) => { await client().conversations.resume(c.id, { signal }); },
         land: async (c, action, into) => { await client().conversations.land(c.id, action, { into, signal }); },
         message: async (c, text) => { await client().conversations.send(c.id, text, { signal }); },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shardflux/cli",
-  "version": "0.24.0",
+  "version": "0.25.0",
   "type": "module",
   "description": "shard: the Shardflux command line. Create an account, sign in, set up keys and billing, then open, run commands in, move files to, suspend, resume and fork serverless agent workspaces.",
   "license": "Apache-2.0",
@@ -48,7 +48,7 @@
     "snappyjs": "0.7.0",
     "ws": "8.22.0",
     "yaml": "2.9.1",
-    "@shardflux/sdk": "^0.27.2"
+    "@shardflux/sdk": "^0.28.0"
   },
   "devDependencies": {
     "@eslint/js": "10.0.1",