gipity 1.1.3 → 1.1.4

package/dist/catalog.js

@@ -36,11 +36,9 @@ export const KITS = [
     { key: 'chatbot', hint: 'drop-in chatbot - persona, guardrails, streaming responses' },
     { key: 'audio-align', hint: 'audio + lyrics -> word-level timing JSON (GPU job)' },
     { key: 'i18n', hint: 'multi-language web apps - language picker, RTL, translations' },
-    { key: 'records', hint: 'registry-driven data plane - generic CRUD, validation, search, audit spine' },
-    { key: 'views', hint: 'registry-driven UI over records - table, forms, kanban' },
-    { key: 'agent-api', hint: 'named API keys for agent/script writes through the records kit' },
     { key: 'contacts', hint: 'multi-source contact layer - LinkedIn/Gmail import, dedupe with provenance' },
     { key: 'stripe', hint: 'charge your users - Stripe checkout, subscriptions, brokered webhooks' },
     { key: 'notify', hint: 'web push notifications - platform-owned keys, works on iOS home screen' },
+    { key: 'servicenow', hint: 'ServiceNow tables as a data source - OAuth pull/write-back/real-time sync' },
 ];
 //# sourceMappingURL=catalog.js.map

package/dist/commands/build.js

@@ -1171,37 +1171,47 @@ async function pickOrCreateProject(projects, existingSlugs) {
     const showAdopt = canAdoptCwd(cwd);
     // Reserve slot 1 for "create new", slot 2 for "use this dir" when shown.
     const reserved = showAdopt ? 2 : 1;
-    // Pickable single-keypress range is 1-9; leave one slot for "Show all"
-    // when there are more projects than fit.
-    const maxRecent = 9 - reserved - 1; // worst case: keep slot 9 free for "show all"
-    const recent = filtered.slice(0, maxRecent);
-    const hasMore = filtered.length > recent.length;
+    // Pickable single-keypress range is 1-9. When every project fits, list
+    // them all; otherwise the actions grow a "Search projects" slot right
+    // after the reserved ones and "Show more" takes slot 9 - accounts with
+    // hundreds of projects can't scroll a dump. Action rows render in a
+    // different color than project rows so the two groups read apart.
+    const fitsAll = filtered.length <= 9 - reserved;
+    const hasMore = !fitsAll;
+    const searchSlot = hasMore ? reserved + 1 : 0;
+    const projectBase = reserved + (hasMore ? 1 : 0); // slots projectBase+1.. are projects
+    const recent = fitsAll ? filtered : filtered.slice(0, 9 - reserved - 2);
+    const moreSlot = hasMore ? projectBase + recent.length + 1 : 0; // always 9 when shown
     // Loop so that a refused/declined adopt-cwd re-shows the picker rather
     // than dropping the user into a shell.
     while (true) {
         const newProjectLabel = formatNewProjectLabel(existingSlugs);
         console.log(`  ${bold('Choose project to open:')}\n`);
-        console.log(`    ${bold('1.')} Create new project          ${muted(`(${newProjectLabel})`)}`);
+        console.log(`    ${bold('1.')} ${info('Create new project')}          ${muted(`(${newProjectLabel})`)}`);
         if (showAdopt) {
-            console.log(`    ${bold('2.')} Use this directory          ${muted(`(${formatCwdLabel(cwd)})`)}`);
+            console.log(`    ${bold('2.')} ${info('Use this directory')}          ${muted(`(${formatCwdLabel(cwd)})`)}`);
         }
-        recent.forEach((p, i) => console.log(`    ${bold(`${i + reserved + 1}.`)} ${p.name} ${muted(`(${p.slug})`)}`));
         if (hasMore) {
-            console.log(`    ${bold(`${recent.length + reserved + 1}.`)} Show all projects`);
+            console.log(`    ${bold(`${searchSlot}.`)} ${info('Search projects')} ${muted(`(${filtered.length} total)`)}`);
+        }
+        recent.forEach((p, i) => console.log(`    ${bold(`${projectBase + i + 1}.`)} ${p.name} ${muted(`(${p.slug})`)}`));
+        if (hasMore) {
+            console.log(`    ${bold(`${moreSlot}.`)} ${info('Show more')}`);
         }
         console.log('');
-        const maxOption = recent.length + reserved + (hasMore ? 1 : 0);
+        const maxOption = projectBase + recent.length + (hasMore ? 1 : 0);
         const idx = await pickOne('Choose', maxOption, 1);
-        // Recent project (slots reserved+1 .. recent.length+reserved).
-        if (idx > reserved && idx <= recent.length + reserved) {
-            return { kind: 'pick', project: recent[idx - reserved - 1] };
+        // Recent project (slots projectBase+1 .. projectBase+recent.length).
+        if (idx > projectBase && idx <= projectBase + recent.length) {
+            return { kind: 'pick', project: recent[idx - projectBase - 1] };
         }
-        // Show all projects (one past the last recent slot).
-        if (hasMore && idx === recent.length + reserved + 1) {
-            const picked = await pickFromAll(filtered);
+        // Search (right after the reserved slots) / Show more (slot 9).
+        if (hasMore && (idx === searchSlot || idx === moreSlot)) {
+            const picked = await browseProjects(filtered, { search: idx === searchSlot });
             if (picked)
                 return { kind: 'pick', project: picked };
-            continue; // user bailed; re-show top picker
+            console.log('');
+            continue; // user backed out; re-show top picker
         }
         // Slot 2 = "Use this directory" (only when shown).
         if (showAdopt && idx === 2) {
@@ -1217,19 +1227,79 @@ async function pickOrCreateProject(projects, existingSlugs) {
         return { kind: 'create-new', project };
     }
 }
-/** Render "Show all projects" with numbered list; returns the picked
- *  project or null if the user picked "create new" (slot 1) or invalid. */
-async function pickFromAll(filtered) {
-    console.log('');
-    console.log(`  ${bold('All projects:')}\n`);
-    console.log(`    ${bold('1.')} Create new project`);
-    filtered.forEach((p, i) => console.log(`    ${bold(`${i + 2}.`)} ${p.name} ${muted(`(${p.slug})`)}`));
+const PROJECT_PAGE_SIZE = 10;
+/** Case-insensitive substring match on project name or slug. An empty or
+ *  whitespace-only query matches everything. Exported for tests. */
+export function searchProjects(all, query) {
+    const q = query.trim().toLowerCase();
+    if (!q)
+        return all;
+    return all.filter(p => p.name.toLowerCase().includes(q) || p.slug.toLowerCase().includes(q));
+}
+/** Paged, searchable project list - the shared renderer behind both the
+ *  "Search projects" and "Show more" picker slots. Shows PROJECT_PAGE_SIZE
+ *  rows at a time with numbering that stays stable across pages, then reads
+ *  a full line (not single-keypress - numbers can exceed 9):
+ *    Enter → next page · <number> → open that project
+ *    s → new search (always over the FULL list, never the current subset)
+ *    q → back to the main picker (returns null).
+ *  `opts.search` starts by prompting for a query instead of listing all.
+ *  Exported for tests. */
+export async function browseProjects(all, opts = {}) {
+    let items = all;
+    let heading = 'All projects';
+    // Prompt for a query and swap the working list to the matches. Returns
+    // false (list unchanged) on empty input or zero matches.
+    const runSearch = async () => {
+        const q = await prompt(`  ${bold('Search projects:')} `);
+        if (!q)
+            return false;
+        const matches = searchProjects(all, q);
+        if (matches.length === 0) {
+            console.log(`  ${muted(`No projects match "${q}".`)}`);
+            return false;
+        }
+        items = matches;
+        heading = `Projects matching "${q}"`;
+        return true;
+    };
     console.log('');
-    const allChoice = await prompt(`  Choose (1-${filtered.length + 1}): `);
-    const allIdx = parseInt(allChoice, 10);
-    if (allIdx >= 2 && allIdx <= filtered.length + 1)
-        return filtered[allIdx - 2];
-    return null;
+    if (opts.search && !(await runSearch()))
+        return null;
+    let shown = 0;
+    while (true) {
+        if (shown < items.length) {
+            const page = items.slice(shown, shown + PROJECT_PAGE_SIZE);
+            if (shown === 0)
+                console.log(`  ${bold(`${heading}`)} ${muted(`(${items.length})`)}\n`);
+            page.forEach((p, i) => console.log(`    ${bold(`${String(shown + i + 1).padStart(3)}.`)} ${p.name} ${muted(`(${p.slug})`)}`));
+            shown += page.length;
+            console.log('');
+        }
+        const more = shown < items.length;
+        const hints = [
+            more ? `Enter = next ${Math.min(PROJECT_PAGE_SIZE, items.length - shown)}` : null,
+            'number = open',
+            's = search',
+            'q = back',
+        ].filter(Boolean).join(' · ');
+        const answer = (await prompt(`  ${bold('Choose')} ${muted(`(${hints})`)}: `)).toLowerCase();
+        if (answer === '' && more)
+            continue; // Enter → next page
+        if (answer === '' || answer === 'q')
+            return null;
+        if (answer === 's') {
+            if (await runSearch()) {
+                shown = 0;
+                console.log('');
+            }
+            continue;
+        }
+        const n = parseInt(answer, 10);
+        if (Number.isInteger(n) && n >= 1 && n <= shown)
+            return items[n - 1];
+        console.log(`  ${muted('Type one of the numbers above, Enter for more, s to search, or q to go back.')}`);
+    }
 }
 /** Show "(~/GipityProjects/project-NNN)" - the exact dir option 1 will
  *  create, so the user can see where their new project will land. */

package/dist/commands/deploy.js

@@ -1,6 +1,6 @@
 import { Command } from 'commander';
 import { post } from '../api.js';
-import { requireConfig } from '../config.js';
+import { requireConfig, resolveApiBase } from '../config.js';
 import { formatSize } from '../utils.js';
 import { success, error as clrError, warning, muted, bold, brand } from '../colors.js';
 import { run, syncBeforeAction } from '../helpers/index.js';
@@ -150,7 +150,11 @@ export const deployCommand = new Command('deploy')
         // for an API-only app the endpoint address IS the deliverable, so name
         // it instead of leaving it to be inferred from a template comment.
         if (d.phases?.some(p => p.name === 'functions')) {
-            console.log(`${muted('Functions:')} POST ${brand(`${config.apiBase}/api/${config.projectGuid}/fn/<name>`)}`);
+            // Print the base the CLI actually calls (resolveApiBase honors the
+            // --api-base flag and GIPITY_API_BASE env), not the raw stored
+            // config.apiBase - otherwise on any override we'd advertise a host we
+            // didn't deploy to and send the caller probing the wrong instance.
+            console.log(`${muted('Functions:')} POST ${brand(`${resolveApiBase()}/api/${config.projectGuid}/fn/<name>`)}`);
             console.log(muted('  (same address on dev and prod; names: gipity fn list; verify the public path: gipity fn call <name> --anon)'));
         }
         await inspectAfter();

package/dist/commands/file.js

@@ -34,6 +34,24 @@ fileCommand
         process.stdout.write(res.data.content);
     }
 }));
+fileCommand
+    .command('url <path>')
+    .description('Durable public URL for a project file - no deploy needed. Reachable by browsers, GPU jobs, and external services the moment the file syncs; ideal for throwaway test fixtures (delete the file to revoke the link).')
+    .option('--download', 'URL forces a download (Content-Disposition: attachment)')
+    .option('--json', 'Output as JSON')
+    .action((path, opts) => run('Url', async () => {
+    const { config } = await resolveProjectContext();
+    const qs = new URLSearchParams({ path });
+    if (opts.download)
+        qs.set('download', '1');
+    const res = await get(`/projects/${config.projectGuid}/files/url?${qs.toString()}`);
+    if (opts.json) {
+        console.log(JSON.stringify(res.data));
+    }
+    else {
+        console.log(res.data.url);
+    }
+}));
 fileCommand
     .command('tree [path]')
     .description('Show the file tree')

package/dist/commands/fn.js

@@ -1,9 +1,9 @@
 import { Command } from 'commander';
 import { get, post, del, publicPost } from '../api.js';
 import { getAuth } from '../auth.js';
-import { requireConfig } from '../config.js';
+import { requireConfig, resolveApiBase } from '../config.js';
 import { error as clrError, bold, muted, success, warning } from '../colors.js';
-import { run, printList, emitField } from '../helpers/index.js';
+import { run, printList, emitField, resolveBody } from '../helpers/index.js';
 import { confirm } from '../utils.js';
 export const fnCommand = new Command('fn')
     .description('Manage functions');
@@ -21,7 +21,7 @@ fnCommand
     // The callable address is the deliverable for API-only apps - name it here
     // rather than leaving it to be inferred from a template comment.
     if (!opts.json && res.data.length > 0) {
-        console.log(muted(`Endpoint: POST ${config.apiBase}/api/${config.projectGuid}/fn/<name>  (same on dev and prod; public path: gipity fn call <name> --anon)`));
+        console.log(muted(`Endpoint: POST ${resolveApiBase()}/api/${config.projectGuid}/fn/<name>  (same on dev and prod; public path: gipity fn call <name> --anon)`));
     }
 }));
 fnCommand
@@ -73,14 +73,14 @@ async function callAnon(projectGuid, name, body) {
 fnCommand
     .command('call <name> [body]')
     .description('Call a function')
-    .option('--data <json>', 'JSON request body')
+    .option('-d, --data <json>', 'JSON request body: inline JSON, @file to read a file, or @- / - for stdin')
+    .option('--file <field=@path>', 'Attach a file as { data, media_type } under <field> (the vision/media service shape), repeatable, e.g. --file image=@receipt.png', (v, acc) => (acc || []).concat(v))
     .option('--anon', 'Call as an anonymous visitor (the public path a signed-out user hits) instead of as your signed-in account')
     .option('--field <path>', 'Print only this field of the result (dot path, e.g. items.0.short_guid)')
     .option('--json', 'Output as JSON')
     .action((name, bodyArg, opts) => run('Call', async () => {
     const config = requireConfig();
-    const raw = bodyArg || opts.data || '{}';
-    const body = JSON.parse(raw);
+    const body = resolveBody(bodyArg || opts.data, opts.file);
     const path = `/api/${config.projectGuid}/fn/${encodeURIComponent(name)}`;
     // Name the calling identity (stderr, so stdout stays parseable). Without
     // this, a "test the anonymous path" call silently runs authenticated as

package/dist/commands/generate.js

@@ -2,11 +2,12 @@ import { Command } from 'commander';
 import { post } from '../api.js';
 import { resolveProjectContext, getConfigPath } from '../config.js';
 import { pushFile } from '../sync.js';
-import { mkdirSync, writeFileSync } from 'fs';
-import { resolve as resolvePath, dirname, relative, isAbsolute } from 'path';
+import { mkdirSync, writeFileSync, readFileSync } from 'fs';
+import { resolve as resolvePath, dirname, relative, isAbsolute, basename } from 'path';
 import { error as clrError, success, muted } from '../colors.js';
 import { printCommandError } from '../helpers/command.js';
 import { withSpinner } from '../progress.js';
+import { guessMime } from '../upload.js';
 import { IMAGE_MODELS_DOC, IMAGE_GEMINI_ASPECT_RATIOS, IMAGE_GEMINI_SIZES, VIDEO_MODELS_DOC, TTS_PROVIDER_DESCRIPTIONS } from '../provider-docs.js';
 /** Download a URL and save to a local file, then push it up to the project so
  *  the cloud (and anything that mirrors it) immediately matches local disk.
@@ -20,12 +21,25 @@ import { IMAGE_MODELS_DOC, IMAGE_GEMINI_ASPECT_RATIOS, IMAGE_GEMINI_SIZES, VIDEO
  *  that gap so the "sandbox auto-mirrors the project" contract holds right after
  *  generation. Best-effort: the local save already succeeded, so a push failure
  *  only warns and points at `gipity sync`. */
-async function downloadFile(url, filename) {
+async function downloadFile(url, filename, explicit) {
     const res = await fetch(url);
     if (!res.ok)
         throw new Error(`Download failed: ${res.status}`);
     const buffer = Buffer.from(await res.arrayBuffer());
-    const outPath = correctExtension(filename, buffer);
+    // An explicit `-o` path is a name the caller has committed to and will chain
+    // the NEXT command against (`--input src.png`, `page eval --camera src.png`),
+    // so the saved path MUST equal what was asked - a predictable path is worth
+    // more than a tidy extension. The model's output format is non-deterministic
+    // (BFL's "png" request comes back as JPEG), so renaming to match the bytes
+    // moves the file out from under the caller's already-written second command:
+    // that is the "saved as .jpg, retry with the right path" wasted turn. Honour
+    // the request; every downstream consumer (browsers, image/video tools, the
+    // edit + camera services) sniffs the bytes, not the extension, so a jpg-in-a-
+    // .png plays and edits fine. For the auto-generated default there is no
+    // committed path, so there we DO name the file after its real bytes.
+    const outPath = explicit ? filename : correctExtension(filename, buffer);
+    if (explicit)
+        noteFormatMismatch(filename, buffer);
     ensureOutputDir(outPath);
     writeFileSync(outPath, buffer);
     const savedPath = resolvePath(outPath);
@@ -85,6 +99,23 @@ function correctExtension(filename, buf) {
         + `saving as ${corrected} so the extension matches the actual bytes.`));
     return corrected;
 }
+/** When the caller committed to an explicit `-o` path we save to it verbatim
+ *  (see downloadFile), but the model's format may not match the extension. Say
+ *  so, and say plainly that the file is at the requested path — so an agent that
+ *  reads this note does NOT go change the path its already-queued next command
+ *  points at (that "retry with .jpg" turn is the whole bug we're closing). */
+function noteFormatMismatch(filename, buf) {
+    const actual = sniffExt(buf);
+    if (!actual)
+        return;
+    const dot = filename.lastIndexOf('.');
+    const asked = dot > 0 ? filename.slice(dot + 1).toLowerCase() : '';
+    if (!asked || canonicalExt(asked) === actual)
+        return;
+    console.error(muted(`Note: ${basename(filename)} holds ${formatName(actual)} bytes though its name ends .${asked} — `
+        + `that's fine (browsers and image/video/edit tools sniff the bytes, not the name). `
+        + `Saved at the exact path you requested; reference it as-is.`));
+}
 /** Create the parent directory of an -o path, so `-o src/audio/ding.mp3` works
  *  in a tree that has no `src/audio/` yet instead of dying on a raw ENOENT.
  *
@@ -116,22 +147,52 @@ async function pushGenerated(savedPath) {
         console.error(muted(`Note: couldn't sync to the cloud automatically (${err.message}). Run \`gipity sync\` before referencing this file in \`gipity sandbox run\`.`));
     }
 }
+/** Read the `--input` image files an edit request is applied to, as base64 +
+ *  mime type. The CLI reads the bytes itself so a photo never has to travel
+ *  through the shell argv (base64 images blow past ARG_MAX — "Argument list too
+ *  long" — the moment you try to inline them), which is exactly the trap an
+ *  agent falls into hand-rolling an edit call with a python one-liner. */
+function readInputImages(paths) {
+    return paths.map((p) => {
+        let buf;
+        try {
+            buf = readFileSync(p);
+        }
+        catch (e) {
+            throw new Error(`can't read --input image ${p} (${e.code || e.message}).`);
+        }
+        const mime = guessMime(p);
+        if (!mime.startsWith('image/')) {
+            throw new Error(`--input ${p} is not an image (${mime}). Edit inputs must be image files.`);
+        }
+        return { data: buf.toString('base64'), mime_type: mime };
+    });
+}
 // ── IMAGE ──────────────────────────────────────────────────────────────
 const imageCommand = new Command('image')
-    .description(`Generate an image from a text prompt using AI.
+    .description(`Generate an image from a text prompt, or EDIT existing images with --input.
 
 Models: ${IMAGE_MODELS_DOC}
 
+Editing (--input): pass one or more source images and the prompt becomes an edit
+instruction applied to them - "make it night time", "add a hat", "remove the car
+in the background", or compose several inputs together. Editing routes to Gemini
+automatically. This is the first-party way to exercise the image-edit flow from
+the CLI; the CLI reads the file bytes itself, so there is no base64/argv fiddling.
+
 Gemini-specific options:
   --aspect-ratio   Control output shape: ${IMAGE_GEMINI_ASPECT_RATIOS}
   --image-size     Control resolution: ${IMAGE_GEMINI_SIZES} (default: 1K)
 
 Examples:
   gipity generate image "a cat wearing a top hat"
+  gipity generate image "make it night time" --input photo.jpg -o edited.png
+  gipity generate image "put the person in the first photo into the second scene" --input person.png --input scene.png
   gipity generate image "landscape sunset" --provider gemini --aspect-ratio 16:9 --image-size 2K
   gipity generate image "product photo" --provider openai --model gpt-image-2 --size 1536x1024 --quality high
   gipity generate image "abstract art" --provider bfl --model flux-2-pro -o art.png`)
-    .argument('<prompt>', 'Text description of the image to generate')
+    .argument('<prompt>', 'Text description of the image, or (with --input) the edit instruction to apply')
+    .option('--input <file>', 'Source image to edit/compose (repeatable). With --input the prompt is an edit instruction; routes to Gemini.', (v, acc) => (acc || []).concat(v))
     .option('--provider <provider>', 'Image provider: openai, bfl, or gemini (default: bfl)')
     .option('--model <model>', 'Model ID (see provider list above)')
     .option('--size <size>', 'Dimensions as WxH, e.g. "1024x1024" (OpenAI/BFL)')
@@ -146,6 +207,7 @@ Examples:
         const { config } = await resolveProjectContext();
         if (opts.output)
             ensureOutputDir(opts.output);
+        const inputImages = opts.input ? readInputImages(opts.input) : undefined;
         const doGenerate = () => post(`/projects/${config.projectGuid}/generate/image`, {
             prompt,
             provider: opts.provider,
@@ -155,13 +217,15 @@ Examples:
             aspect_ratio: opts.aspectRatio,
             image_size: opts.imageSize,
             seed: Number.isFinite(opts.seed) ? opts.seed : undefined,
+            input_images: inputImages,
         });
+        const verb = inputImages ? 'Editing image…' : 'Generating image…';
         const result = opts.json
             ? await doGenerate()
-            : await withSpinner('Generating image…', doGenerate, { done: null });
+            : await withSpinner(verb, doGenerate, { done: null });
         const ext = result.content_type.includes('png') ? 'png' : 'jpg';
         const filename = opts.output || `generated.${ext}`;
-        const savedPath = await downloadFile(result.url, filename);
+        const savedPath = await downloadFile(result.url, filename, !!opts.output);
         if (opts.json) {
             console.log(JSON.stringify({ ...result, saved: savedPath }));
         }
@@ -223,7 +287,7 @@ Examples:
             ? await doGenerate()
             : await withSpinner('Generating video…', doGenerate, { done: null });
         const filename = opts.output || 'generated.mp4';
-        const savedPath = await downloadFile(result.url, filename);
+        const savedPath = await downloadFile(result.url, filename, !!opts.output);
         if (opts.json) {
             console.log(JSON.stringify({ ...result, saved: savedPath }));
         }
@@ -287,7 +351,7 @@ Examples:
             ? await doGenerate()
             : await withSpinner('Generating speech…', doGenerate, { done: null });
         const filename = opts.output || 'speech.mp3';
-        const savedPath = await downloadFile(result.url, filename);
+        const savedPath = await downloadFile(result.url, filename, !!opts.output);
         if (opts.json) {
             console.log(JSON.stringify({ ...result, saved: savedPath }));
         }
@@ -340,7 +404,7 @@ Examples:
             ? await doGenerate()
             : await withSpinner('Generating music…', doGenerate, { done: null });
         const filename = opts.output || 'music.mp3';
-        const savedPath = await downloadFile(result.url, filename);
+        const savedPath = await downloadFile(result.url, filename, !!opts.output);
         if (opts.json) {
             console.log(JSON.stringify({ ...result, saved: savedPath }));
         }
@@ -391,7 +455,7 @@ Examples:
             ? await doGenerate()
             : await withSpinner('Generating sound effect…', doGenerate, { done: null });
         const filename = opts.output || 'sound.mp3';
-        const savedPath = await downloadFile(result.url, filename);
+        const savedPath = await downloadFile(result.url, filename, !!opts.output);
         if (opts.json) {
             console.log(JSON.stringify({ ...result, saved: savedPath }));
         }

package/dist/commands/job.js

@@ -2,7 +2,7 @@ import { Command } from 'commander';
 import { get, post, del, getBaseUrl, getAuthHeader } from '../api.js';
 import { requireConfig } from '../config.js';
 import { error as clrError, bold, muted, success, warning as warn } from '../colors.js';
-import { run, printList } from '../helpers/index.js';
+import { run, printList, resolveBody, parseDuration } from '../helpers/index.js';
 export const jobCommand = new Command('job')
     .description('Run long jobs (CPU/GPU)')
     .addHelpText('after', '\nCPU sandbox or GPU (gpu-small=L4, gpu-medium=A10G, gpu-large=A100, gpu-huge=H100). Declared in the gipity.yaml jobs: phase; submit and poll via the subcommands below.');
@@ -23,14 +23,14 @@ jobCommand
 }));
 jobCommand
     .command('submit <name> [body]')
-    .description('Submit a job (returns a run guid; poll with `job status <guid>`)')
-    .option('--data <json>', 'JSON input body')
+    .description('Submit a job (returns a run guid; block on it with `job wait <guid>`)')
+    .option('-d, --data <json>', 'JSON input body: inline JSON, @file to read a file, or @- / - for stdin')
+    .option('--file <field=@path>', 'Attach a file as { data, media_type } under <field> (the vision/media service shape), repeatable, e.g. --file image=@scan.png', (v, acc) => (acc || []).concat(v))
     .option('--idempotency-key <key>', 'Idempotency key (replays return the existing run)')
     .option('--json', 'Output as JSON')
     .action((name, bodyArg, opts) => run('Submit', async () => {
     const config = requireConfig();
-    const raw = bodyArg || opts.data || '{}';
-    const input = JSON.parse(raw);
+    const input = resolveBody(bodyArg || opts.data, opts.file);
     const body = { input };
     if (opts.idempotencyKey)
         body.idempotency_key = opts.idempotencyKey;
@@ -41,6 +41,12 @@ jobCommand
     else {
         const tag = res.data.replayed ? warn(' (replayed)') : '';
         console.log(`${bold(res.data.run_guid)}  ${muted(res.data.status)}${tag}`);
+        // Awaiting the run is the natural next step after every submit; point the
+        // agent at the blocking command so it doesn't hand-roll a status poll loop.
+        const TERMINAL = new Set(['success', 'failed', 'cancelled', 'canceled', 'error']);
+        if (!TERMINAL.has(res.data.status)) {
+            console.error(muted(`Block until it finishes: gipity job wait ${res.data.run_guid}`));
+        }
     }
 }));
 jobCommand
@@ -66,6 +72,71 @@ jobCommand
     if (r.output)
         console.log(`output: ${JSON.stringify(r.output)}`);
 }));
+jobCommand
+    .command('wait <runGuid>')
+    .description('Block until a job run finishes, or exit at --timeout so the shell never hangs (poll again to keep waiting)')
+    .option('--timeout <seconds>', 'Max seconds to wait before giving up and reporting current progress. Bare number = seconds; an explicit unit (90s) means the same here and on `sandbox run --timeout`.', '90')
+    .option('--interval <seconds>', 'Seconds between polls', '3')
+    .option('--json', 'Output as JSON')
+    .action((runGuid, opts) => run('Wait', async () => {
+    const config = requireConfig();
+    // Terminal states end the wait; anything else means "still working, keep polling".
+    const TERMINAL = new Set(['success', 'failed', 'cancelled', 'canceled', 'error']);
+    const durOpt = parseDuration(opts.timeout, 's');
+    const timeoutSec = durOpt ? Math.max(1, Math.round(durOpt.value)) : parseInt(opts.timeout, 10);
+    const timeout = Number.isFinite(timeoutSec) && timeoutSec > 0 ? timeoutSec : 90;
+    const interval = Math.max(1, parseInt(opts.interval, 10) || 3);
+    const deadline = Date.now() + timeout * 1000;
+    const fetchRun = async () => (await get(`/projects/${config.projectGuid}/jobs/runs/${encodeURIComponent(runGuid)}`)).data;
+    let r = await fetchRun();
+    let lastProgress = '';
+    while (!TERMINAL.has(r.status) && Date.now() < deadline) {
+        // Surface progress changes to stderr so an agent watching sees liveness
+        // without the poll noise polluting the machine-readable stdout result.
+        if (!opts.json) {
+            const prog = r.progress_pct != null
+                ? `${Math.round(r.progress_pct * 100)}%${r.progress_message ? ` (${r.progress_message})` : ''}`
+                : r.status;
+            if (prog !== lastProgress) {
+                console.error(muted(`… ${prog}`));
+                lastProgress = prog;
+            }
+        }
+        const remaining = deadline - Date.now();
+        if (remaining <= 0)
+            break;
+        await new Promise(res => setTimeout(res, Math.min(interval * 1000, remaining)));
+        r = await fetchRun();
+    }
+    const done = TERMINAL.has(r.status);
+    if (opts.json) {
+        console.log(JSON.stringify(done ? r : { ...r, waiting: true, timed_out: true }));
+    }
+    else if (!done) {
+        // Not an error - the job is simply still going. Say so plainly and tell
+        // the agent exactly how to resume, then exit non-zero so a chained `&&`
+        // doesn't proceed as if the run had finished.
+        const prog = r.progress_pct != null ? ` ${Math.round(r.progress_pct * 100)}%` : '';
+        console.log(`${warn('still running')}${prog}${r.progress_message ? ` (${r.progress_message})` : ''}  ${muted(runGuid)}`);
+        console.log(muted(`Not finished after ${timeout}s. Run \`gipity job wait ${runGuid}\` again to keep waiting.`));
+    }
+    else {
+        const statusColor = r.status === 'success' ? success : clrError;
+        console.log(`${statusColor(r.status)}  ${muted(r.guid)}`);
+        if (r.duration_ms != null)
+            console.log(`duration: ${r.duration_ms}ms`);
+        if (r.error)
+            console.log(`${clrError('error:')} ${r.error}`);
+        if (r.output)
+            console.log(`output: ${JSON.stringify(r.output)}`);
+    }
+    // Exit codes: success → 0, failed/cancelled → 1, still-running-at-timeout → 2
+    // (distinct from a real failure so agents can tell "not yet" from "broke").
+    if (!done)
+        process.exit(2);
+    if (r.status !== 'success')
+        process.exit(1);
+}));
 jobCommand
     .command('runs <name>')
     .description('List recent runs for a job')
@@ -87,6 +158,7 @@ jobCommand
     .description('Stream live logs for a job run (--no-follow for a one-shot snapshot)')
     .option('--follow', 'Stream via SSE (default)', true)
     .option('--no-follow', 'One-shot snapshot of run state instead of streaming')
+    .option('--timeout <seconds>', 'Stop streaming after N seconds and exit cleanly, so a bounded peek at the live log never hangs the shell (no shell `timeout` wrapper needed). Bare number = seconds; unit (20s) also accepted.')
     .option('--json', 'Output as JSON')
     .action((runGuid, opts) => run('Logs', async () => {
     const config = requireConfig();
@@ -95,6 +167,16 @@ jobCommand
         console.log(opts.json ? JSON.stringify(res.data) : JSON.stringify(res.data, null, 2));
         return;
     }
+    // Optional bounded peek: close the stream after --timeout seconds instead of
+    // holding open until the run finishes. Lets an agent glance at early stdout
+    // (e.g. catch an import error during cold start) without wrapping the command
+    // in a shell `timeout`, then poll again to keep watching.
+    let peekSeconds = 0;
+    if (opts.timeout != null) {
+        const dur = parseDuration(String(opts.timeout), 's');
+        const secs = dur ? dur.value : parseFloat(String(opts.timeout));
+        peekSeconds = Number.isFinite(secs) && secs > 0 ? secs : 0;
+    }
     // SSE stream. Manual fetch + line buffering - Node's EventSource isn't built-in,
     // and the SSE format is simple enough to parse inline (event: <name>\ndata: <json>\n\n).
     const url = `${getBaseUrl()}/projects/${config.projectGuid}/jobs/runs/${encodeURIComponent(runGuid)}/logs/stream`;
@@ -102,8 +184,28 @@ jobCommand
     const headers = { 'Accept': 'text/event-stream' };
     if (authHeader)
         headers.Authorization = authHeader;
-    const res = await fetch(url, { headers });
+    // Abort the underlying request when the peek window elapses so the socket is
+    // torn down cleanly rather than left dangling.
+    const controller = new AbortController();
+    let peekTimer;
+    let peekedOut = false;
+    if (peekSeconds > 0) {
+        peekTimer = setTimeout(() => { peekedOut = true; controller.abort(); }, peekSeconds * 1000);
+    }
+    let res;
+    try {
+        res = await fetch(url, { headers, signal: controller.signal });
+    }
+    catch (e) {
+        if (peekedOut) {
+            console.error(muted(`… still streaming after ${peekSeconds}s. Run \`gipity job logs ${runGuid} --timeout ${Math.round(peekSeconds)}\` again to keep watching, or \`gipity job wait ${runGuid}\` to block until it finishes.`));
+            return;
+        }
+        throw e;
+    }
     if (!res.ok || !res.body) {
+        if (peekTimer)
+            clearTimeout(peekTimer);
         console.error(clrError(`Failed to open stream: HTTP ${res.status}`));
         process.exit(1);
     }
@@ -112,9 +214,24 @@ jobCommand
     let buffer = '';
     let currentEvent = '';
     while (true) {
-        const { done, value } = await reader.read();
-        if (done)
+        let chunk;
+        try {
+            chunk = await reader.read();
+        }
+        catch (e) {
+            // Peek window elapsed mid-stream: report cleanly and exit 0 (not an error).
+            if (peekedOut) {
+                console.error(muted(`… still streaming after ${peekSeconds}s. Run \`gipity job logs ${runGuid} --timeout ${Math.round(peekSeconds)}\` again to keep watching, or \`gipity job wait ${runGuid}\` to block until it finishes.`));
+                return;
+            }
+            throw e;
+        }
+        const { done, value } = chunk;
+        if (done) {
+            if (peekTimer)
+                clearTimeout(peekTimer);
             break;
+        }
         buffer += decoder.decode(value, { stream: true });
         let nl;
         while ((nl = buffer.indexOf('\n')) >= 0) {