mlai-code 0.3.7 → 0.3.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -327,6 +327,7 @@ Working rules:
327
327
  - Change source files with Edit (exact text replacement) or Write, never with sed -i, perl -pi or a python/node script that rewrites the file: those break silently on JSX/TSX quotes and braces. After a batch of edits, run the type check or build before you report anything as working.
328
328
  - You have live web access in every turn: use mcp__mlai__web_search and mcp__mlai__web_fetch whenever the answer depends on current public facts you cannot see in the repository (documentation and versions, but also weather, news, prices, scores or local time). Never say you lack web, real-time or weather access. For research answers, record the material claims with mcp__mlai__evidence and link the source URLs. Never put credentials or private code in queries.
329
329
  - After changing code, run the relevant tests, build or type check with Bash and read the real exit status. A passing unrelated suite does not prove the requested behavior. Never claim something works without running it.
330
+ - Keep a check's exit status the runner's own: no `| tail`/`| head` without `set -o pipefail`, and no `; echo $?`, an echo of PIPESTATUS, `|| true` or another command after the runner (for long output use `set -o pipefail; npm test 2>&1 | tail -40`). Run checks in the foreground; a check sent to the background counts only when you read its result with TaskOutput. In the final message, report only the checks that ran in this turn and their real results; never repeat counts from an earlier turn as if they ran now.
330
331
  - Do not fabricate data, mocks or placeholder implementations in shipped code unless the user asked for them.
331
332
  - Do what the user asked, and only that (BUG-0226). A request to install a package, run a command or answer a question is done when that is done: do not add features, tools, commands or files nobody asked for, do not rename the package, remove "private" from package.json, publish, install globally or push unless the user asked for it. When extra work looks useful, finish the request, then suggest it in one sentence and ask; do not start it.
332
333
  - Once the user approves a plan or task list, build exactly what it says (BUG-0245). If an approved item turns out to need a different approach, stop and ask before changing it; if you had to change it, the final message must name the item, what you did instead and why, in plain words.
@@ -683,7 +684,10 @@ class StreamMapper:
683
684
  except Exception: pass
684
685
  def todos(self, items):
685
686
  shown = [{'text': str(t.get('title', ''))[:300], 'status': t.get('status') if t.get('status') in ('pending', 'in_progress', 'done') else 'pending'} for t in items if isinstance(t, dict)][:40]
686
- write('todos.json', shown); event('todos', items=shown)
687
+ write('todos.json', shown)
688
+ # The same list again (a repeated TodoList call) is not shown twice (tester report, CLI 0.3.8).
689
+ if shown != getattr(self, 'last_todos', None): event('todos', items=shown)
690
+ self.last_todos = shown
687
691
  def announce(self, name, args):
688
692
  if name == 'Bash': event('command', command=str(args.get('command', ''))[:20000])
689
693
  elif name in ('Agent', 'AgentSwarm'): event('subagent', state='running', content=str(args.get('description') or args.get('prompt') or '')[:400])
@@ -711,16 +715,25 @@ class StreamMapper:
711
715
  try: args = json.loads(fn.get('arguments') or '{}')
712
716
  except ValueError: args = {}
713
717
  self.calls[call.get('id')] = (name, args)
718
+ if name == 'Bash' and not args.get('run_in_background'): proc_watch.foreground(call.get('id'), args.get('command')) # CLI r7
714
719
  if name == 'TodoList' and isinstance(args.get('todos'), list): self.todos(args['todos'])
715
720
  elif len(calls) == 1: self.announce(name, args)
716
721
  # Parallel calls are announced with their results so each step pairs with its own output.
717
722
  self.deferred = {c.get('id') for c in calls} if len(calls) > 1 else set()
718
723
  return
724
+ if role == 'user':
725
+ # A background check finished and the engine told the agent so (it may read the log instead of TaskOutput).
726
+ content = msg.get('content')
727
+ if isinstance(content, list): content = '\n'.join(p.get('text', '') for p in content if isinstance(p, dict))
728
+ self.background_notice(str(content or ''))
729
+ return
719
730
  if role == 'tool':
720
731
  name, args = self.calls.get(msg.get('tool_call_id'), ('', {}))
732
+ proc_watch.done(msg.get('tool_call_id'))
721
733
  content = msg.get('content')
722
734
  if isinstance(content, list): content = '\n'.join(p.get('text', '') for p in content if isinstance(p, dict))
723
735
  content = str(content or '')
736
+ if name in ('TaskOutput', 'WaitFor'): self.background_result(content)
724
737
  exit_code = re.search(r'Command failed with exit code: (\d+)', content)
725
738
  code = int(exit_code.group(1)) if exit_code else (1 if FAILED.search(content) else 0)
726
739
  # A refused call never ran: it is not a result, and never replaces the last real result of that command.
@@ -734,9 +747,16 @@ class StreamMapper:
734
747
  if name == 'TodoList': return
735
748
  if msg.get('tool_call_id') in getattr(self, 'deferred', set()): self.announce(name, args)
736
749
  check_code, integrity = code, ''
737
- if name == 'Bash' and is_check(str(args.get('command', ''))) and not args.get('run_in_background') and not blocked:
750
+ command = str(args.get('command', '')) if name == 'Bash' else ''
751
+ # Round 6: a check started in the background, or a foreground check the engine moved there after its
752
+ # timeout, has not finished: its result is the later TaskOutput or completion notice, not this 0.
753
+ moved = name == 'Bash' and not code and bool(BACKGROUND_STARTED.search(content))
754
+ checkish = name == 'Bash' and not blocked and (is_check(command) or verification.script_check(command, '' if moved else content))
755
+ if checkish and moved: self.background_started(content, command)
756
+ checkish = checkish and not moved and not args.get('run_in_background')
757
+ if checkish:
738
758
  # EXEC-001: `npm test | tail` exits with tail's status. Reconcile with the runner's own summary.
739
- check_code, integrity = verification.check_exit(str(args.get('command', '')), code, content, is_check)
759
+ check_code, integrity = verification.check_exit(command, code, content, lambda t: is_check(t) or verification.script_check(t))
740
760
  event('output', output=content[:12000], returncode=code if check_code is None else check_code, **({'integrity': integrity} if integrity else {}), **({'blocked': True} if blocked else {}))
741
761
  if name == 'Bash' and args.get('run_in_background') and not code:
742
762
  # BUG-0203: remember the start command so a new computer can offer Restart (never restarted by itself).
@@ -759,16 +779,10 @@ class StreamMapper:
759
779
  commands = (commands if isinstance(commands, list) else []) + [{'command': command[:2000], 'returncode': code, 'time': time.time(), **({'blocked': True} if blocked else {})}]
760
780
  write('kimi-commands.json', commands[-300:])
761
781
  except Exception: pass
762
- if blocked: pass
763
- elif is_check(command) and not args.get('run_in_background'):
764
- record = {'label': clip(command, 160), 'command': command[:2000], 'returncode': check_code, 'executed': True, 'scope': 'supporting' if st.get('inspect') else 'repository', 'output': content[-4000:], 'time': time.time()}
765
- if integrity: record.update(shellReturncode=code, integrity=integrity); event('note', content=integrity)
782
+ if blocked or moved: pass
783
+ elif checkish:
784
+ self.record_check(command, code, check_code, integrity, content)
766
785
  code = check_code if check_code is not None else code
767
- key = check_key(record['command'])
768
- checks = [c for c in load(ROOT, 'checks.json', []) if check_key(c.get('command')) != key] + [record]
769
- write('checks.json', checks[-20:]); event('verification', **record)
770
- if check_code == 0: st['last_check'] = time.time()
771
- elif check_code is not None: st['last_failed_check'] = time.time()
772
786
  elif code == 0 and not args.get('run_in_background') and not st.get('inspect') and not HOOK_BLOCKED.search(content):
773
787
  # BUG-0542: no test suite here; running the changed program and seeing it work is the check.
774
788
  try:
@@ -785,6 +799,66 @@ class StreamMapper:
785
799
  write('checks.json', checks[-20:]); event('verification', **remote)
786
800
  save_state(st)
787
801
 
802
+ def record_check(self, command, code, check_code, integrity, content):
803
+ st = self.state
804
+ record = {'label': clip(command, 160), 'command': command[:2000], 'returncode': check_code, 'executed': True, 'scope': 'supporting' if st.get('inspect') else 'repository', 'output': content[-4000:], 'time': time.time()}
805
+ if integrity: record.update(shellReturncode=code, integrity=integrity); event('note', content=integrity)
806
+ key = check_key(record['command'])
807
+ checks = [c for c in load(ROOT, 'checks.json', []) if check_key(c.get('command')) != key] + [record]
808
+ write('checks.json', checks[-20:]); event('verification', **record)
809
+ if check_code == 0: st['last_check'] = time.time()
810
+ elif check_code is not None: st['last_failed_check'] = time.time()
811
+ def background_started(self, content, command):
812
+ m = re.search(r'^task_id:\s*(\S+)', content, re.M)
813
+ if not m: return
814
+ pending = load(ROOT, BACKGROUND_CHECKS, {})
815
+ pending = pending if isinstance(pending, dict) else {}
816
+ pending[m.group(1)] = {'command': command[:2000], 'time': time.time()}
817
+ write(BACKGROUND_CHECKS, dict(list(pending.items())[-40:]))
818
+ event('note', content='Check moved to the background; its result counts once it finishes: ' + clip(command, 160))
819
+ def settle_background(self, task_id, code, output, command=None):
820
+ pending = load(ROOT, BACKGROUND_CHECKS, {})
821
+ pending = pending if isinstance(pending, dict) else {}
822
+ entry = pending.pop(task_id, None)
823
+ command = (entry or {}).get('command') or command
824
+ if not command or not (entry or is_check(command) or verification.script_check(command, output)): return
825
+ write(BACKGROUND_CHECKS, pending)
826
+ check_code, integrity = verification.check_exit(command, code, output, lambda t: is_check(t) or verification.script_check(t))
827
+ self.record_check(command, code, check_code, integrity, output)
828
+ save_state(self.state)
829
+ def background_result(self, content):
830
+ """TaskOutput or WaitFor on finished background tasks: per task a record (`status: completed|failed`,
831
+ `exit_code: N`, `command: ...`) starting with `Wall time:`, then its [output]."""
832
+ blocks = re.split(r'(?m)^(?=Wall time:)', content)
833
+ for block in (blocks[1:] if len(blocks) > 1 else blocks): self.background_record(block)
834
+ def background_record(self, content):
835
+ head, _, output = content.partition('\n[output]\n')
836
+ fields = dict(re.findall(r'^(task_id|status|exit_code|command|kind):\s*(.*)$', head, re.M))
837
+ if fields.get('kind', 'process') != 'process' or fields.get('status') not in ('completed', 'failed', 'killed', 'timed_out'): return
838
+ try: code = int(fields.get('exit_code'))
839
+ except (TypeError, ValueError): code = 0 if fields.get('status') == 'completed' else 1
840
+ if fields.get('status') != 'completed' and not code: code = 1
841
+ self.settle_background(fields.get('task_id', ''), code, output.strip(), fields.get('command'))
842
+ def background_notice(self, content):
843
+ m = BACKGROUND_NOTICE.search(content)
844
+ if not m: return
845
+ task_id, kind = m.group(2), m.group(1)
846
+ pending = load(ROOT, BACKGROUND_CHECKS, {})
847
+ if not isinstance(pending, dict) or task_id not in pending: return
848
+ output = ''
849
+ path = re.search(r'<output-file path="([^"]+)"', content)
850
+ if path:
851
+ try:
852
+ with open(path.group(1), 'rb') as f:
853
+ f.seek(0, 2); size = f.tell(); f.seek(max(0, size - 8000)); output = f.read().decode('utf-8', 'replace')
854
+ except OSError: pass
855
+ code = re.search(r'exit(?:ed with)? code:?\s*(-?\d+)', content, re.I)
856
+ self.settle_background(task_id, int(code.group(1)) if code else (0 if kind == 'completed' else 1), output)
857
+
858
+ BACKGROUND_CHECKS = 'kimi-background-checks.json'
859
+ BACKGROUND_STARTED = re.compile(r'^task_id:\s*\S+[\s\S]*^automatic_notification:\s*true', re.M)
860
+ BACKGROUND_NOTICE = re.compile(r'<notification\b[^>]*\btype="task\.(completed|failed|killed|timed_out)"[^>]*\bsource_kind="background_task"[^>]*\bsource_id="([^"]+)"')
861
+
788
862
  PROSE_PATH = re.compile(r'\.(?:md|mdx|markdown|rst|adoc|txt)$', re.I)
789
863
  PUSHED = re.compile(r'(^|[;&|(\s])(git push\b|gh pr (create|merge)\b)')
790
864
  CI_OBSERVED = re.compile(r'(^|[;&|(\s])(gh pr checks\b|gh run watch\b[^;&|]*--exit-status)')
@@ -862,11 +936,11 @@ def recheck_stale(state, env, seconds_left, limit=3):
862
936
  if budget < 20 or stopped(): break
863
937
  command = str(check.get('command'))
864
938
  began = time.time()
865
- try:
866
- r = subprocess.run(['bash', '-lc', command], cwd=REPO, env=env, capture_output=True, text=True, timeout=min(REPLAY_SECONDS, budget))
867
- code, output = r.returncode, (r.stdout + r.stderr)[-4000:]
868
- except subprocess.TimeoutExpired:
869
- code, output = None, 'Timed out when rerun on the final code.'
939
+ # Bounded on every OS: output goes to a file and the whole tree is stopped on timeout or Esc (a headless browser
940
+ # left by an e2e script kept a Windows run at "Working" for 45 minutes after its final answer).
941
+ code, output, why = verification.bounded_run(['bash', '-lc', command], cwd=REPO, env=env, timeout=int(min(REPLAY_SECONDS, budget)), stop=stopped)
942
+ if why == 'stopped': break
943
+ if code is None: output = (output + '\n' if output else '') + 'Timed out when rerun on the final code.'
870
944
  budget -= time.time() - began
871
945
  check_code, integrity = verification.check_exit(command, code, output, is_check) if code is not None else (None, '')
872
946
  code = check_code if check_code is not None else code
@@ -962,6 +1036,17 @@ def network_note(config):
962
1036
  extra = [d for d in net.get('domains') or [] if isinstance(d, str)][:40]
963
1037
  return 'Internet access: allowlist (GitHub, npm, PyPI, Hugging Face, Exa and the model APIs' + ('; also allowed by the user: ' + ', '.join(extra) if extra else '') + '). Other hosts are blocked and fail as "Could not resolve host"; when a task needs one, call mcp__mlai__network with the domain and reason instead of retrying.\n'
964
1038
 
1039
+ def windows_note():
1040
+ """Windows bug list (round 6): after the browser check failed, the agent built its own Puppeteer harness in
1041
+ ~/taskflow/.e2e-tmp and `npm init -y` refused the folder name; many calls were spent on it."""
1042
+ busybox = bool(os.getenv('MLAI_BUSYBOX'))
1043
+ shell, drive = ('busybox sh (the sandbox shell)', 'C:/') if busybox else ('Git Bash', '/c/')
1044
+ return ('This computer runs Windows. Shell commands run in ' + shell + ', a POSIX shell: use forward slashes, drives as ' + drive + '..., '
1045
+ 'and /dev/null works there; do not use PowerShell or cmd syntax in shell commands. Windows programs live under '
1046
+ '"' + drive + 'Program Files". A scratch folder you run `npm init -y` in needs a valid package name (lowercase, no leading dot), '
1047
+ 'so do not name it like ".e2e-tmp". If the browser tool says it cannot run here, do not build a replacement '
1048
+ '(Puppeteer, Playwright scripts, the system Chrome or Edge): verify with the project\'s tests and build and say the browser check was not available.\n')
1049
+
965
1050
  def workspace_note(config, event):
966
1051
  """Jobs (restart the ones that died), project setup and environment facts for the agent's instructions."""
967
1052
  note = ''
@@ -988,6 +1073,7 @@ def workspace_note(config, event):
988
1073
  note += env_setup.tools_line(ROOT) + '\n'
989
1074
  except Exception: pass
990
1075
  note += R.preview_build_note()
1076
+ if sys.platform == 'win32': note += windows_note()
991
1077
  if config.get('conversation_route', 'build') == 'build':
992
1078
  try:
993
1079
  import preview
@@ -1286,7 +1372,7 @@ def main():
1286
1372
  research_proxy = start_research_proxy()
1287
1373
  write('status.json', {'state': 'running', 'started': time.time(), 'boot': boot_id(), 'process': identity(os.getpid()), 'harness': 'kimi'})
1288
1374
  (ROOT / 'kimi-stderr.log').unlink(missing_ok=True)
1289
- for name in ('kimi-state.json', 'kimi-progress.json', 'kimi-hook.json', 'usage.json', 'kimi-stop-count', 'design-browser-evidence.json', 'design-review.json', 'acceptance.json', 'budget-declined', 'hard-deny-targets.json', BLOCKED_CALLS): (ROOT / name).unlink(missing_ok=True)
1375
+ for name in ('kimi-state.json', 'kimi-progress.json', 'kimi-hook.json', 'usage.json', 'kimi-stop-count', 'design-browser-evidence.json', 'design-review.json', 'browser-unavailable.json', 'acceptance.json', 'budget-declined', 'hard-deny-targets.json', BACKGROUND_CHECKS, BLOCKED_CALLS): (ROOT / name).unlink(missing_ok=True)
1290
1376
  # "Approve all" covers the rest of the request: a Resume of the same request keeps it, a new request asks afresh.
1291
1377
  if not config.get('resuming') or config.get('subagent'): (ROOT / 'kimi-approve-all').unlink(missing_ok=True)
1292
1378
  shutil.rmtree(ROOT / 'acceptance', ignore_errors=True)
@@ -1454,6 +1540,9 @@ def main():
1454
1540
  elif time.time() - (load(ROOT, 'kimi-stopped', {}) or {}).get('time', 1e18) > FINISH_GRACE: killed['reason'] = 'finished'
1455
1541
  if killed['reason']:
1456
1542
  if killed['reason'] == 'finished': event('note', content='Work finished; background processes such as preview servers keep running')
1543
+ # CLI r7: Windows has no process groups; end every process this run owns first, also a headless
1544
+ # browser whose parent already exited (it holds the engine's pipes, so Stop never finished).
1545
+ if os.name == 'nt' and killed['reason'] != 'finished': proc_watch.kill_all(child.pid, supervisor)
1457
1546
  try:
1458
1547
  os.killpg(child.pid, signal.SIGTERM)
1459
1548
  # Up to 3 s to exit cleanly, but no longer than it takes: Stop used to wait the full 3 s (BUG-0133).
@@ -408,7 +408,19 @@ def final_issues(config, st, answer, done, model, root, repo, event, allow_accep
408
408
  except (OSError, ValueError): records = []
409
409
  report = browser_review(records, fingerprint(repo, st.get('base') or 'HEAD'))
410
410
  (Path(root) / 'design-review.json').write_text(json.dumps(report)); event('design_review', designReview=report)
411
- if report['status'] != 'passed':
411
+ unavailable = None
412
+ try: unavailable = json.loads((Path(root) / 'browser-unavailable.json').read_text())
413
+ except (OSError, ValueError): pass
414
+ if report['status'] != 'passed' and unavailable:
415
+ # Browser checks cannot run on this computer: asking again only loops the run (27 minutes in one Windows
416
+ # report). The review stays "not verified" and the agent's summary says why.
417
+ if 'design-unavailable' not in done:
418
+ done.add('design-unavailable')
419
+ event('note', content='Browser checks are not available on this computer, so the design review is reported as not verified.')
420
+ elif report['status'] != 'passed' and 'design-final' in done:
421
+ pass # asked once already in a final round; the outer bridge reports it as unresolved instead of looping
422
+ elif report['status'] != 'passed':
423
+ done.add('design-final')
412
424
  issues.append(report['message'] + ' Start the app with mcp__mlai__preview {"action":"start"}, then run mcp__mlai__browser at width 390 and at width 1280, each with at least one click/fill/press and an assert_text. Fix overflow, console or page errors and failed requests, then check again.')
413
425
  from conversation import research_required
414
426
  from evidence import EvidenceLedger
@@ -107,10 +107,10 @@ def steer_block(messages, stopping=False):
107
107
 
108
108
  def wait_decision(request, seconds=540, strict=False):
109
109
  """One approval at a time even when Kimi runs tool calls in parallel. Strict (repository policy) reviews ignore "Approve all"."""
110
- import fcntl
110
+ from winproc import lock_file
111
111
  queued = time.time()
112
112
  with (ROOT / 'approval.lock').open('a') as lock:
113
- fcntl.flock(lock, fcntl.LOCK_EX)
113
+ lock_file(lock)
114
114
  # BUG-0251: a call that queued behind an approval the user then rejected (parallel tool calls of one step)
115
115
  # is rejected too, so a leftover card can never run a change the user just said no to.
116
116
  if rejected_since(queued): block('The user rejected a related action in this step, so this call was not run. Do not retry it; explain what you would change and ask.')
@@ -179,9 +179,9 @@ def _wait(request, seconds):
179
179
 
180
180
  def wait_plan(request, seconds=540):
181
181
  """Plan review: returns the raw verdict (approve | approve:0,2 | reject), or None on timeout."""
182
- import fcntl
182
+ from winproc import lock_file
183
183
  with (ROOT / 'approval.lock').open('a') as lock:
184
- fcntl.flock(lock, fcntl.LOCK_EX)
184
+ lock_file(lock)
185
185
  save('pending.json', request); event('approval', **request)
186
186
  decision = ROOT / ('decision-' + request['id']); deadline = time.time() + seconds
187
187
  while not decision.exists():
@@ -859,7 +859,9 @@ def stop(payload, st):
859
859
  from quality import fingerprint
860
860
  report = browser_review(load('design-browser-evidence.json', []), fingerprint(REPO, st.get('base') or 'HEAD'))
861
861
  save('design-review.json', report); event('design_review', designReview=report)
862
- if report['status'] != 'passed':
862
+ if report['status'] != 'passed' and (ROOT / 'browser-unavailable.json').exists():
863
+ done.add('design') # the browser cannot run here; the agent was told to verify with tests and build instead
864
+ elif report['status'] != 'passed':
863
865
  done.add('design'); issues.append(report['message'] + ' Start the app with mcp__mlai__preview {"action":"start"}, then run mcp__mlai__browser at width 390 and at width 1280, each with at least one click/fill/press and an assert_text. Fix overflow, console or page errors and failed requests.')
864
866
  except Exception: pass
865
867
  if 'evidence' not in done:
@@ -17,9 +17,9 @@ PHOTO_HOSTS = ('pixabay.com', 'cdn.pixabay.com')
17
17
  LOGO_HOSTS = ('asset.brandfetch.io', 'cdn.brandfetch.io', 'asset.brandfetch.com')
18
18
  CAPS = {'stock': 40, 'brand': 6}
19
19
 
20
- STOCK_TOOL = {'name': 'stock_photo', 'description': 'Find a real photograph on Pixabay and save it under public/stock/ (free, no credits). Use for people, places, products, teams and textures; use generate_image for bespoke art. Returns the saved path, size, photographer credit and other matches; call again with pick=<id> to use a different match.',
20
+ STOCK_TOOL = {'name': 'stock_photo', 'description': 'Find a real photograph on Pixabay and save it under public/stock/, or the project folder given in filename (free, no credits). Use for people, places, products, teams and textures; use generate_image for bespoke art. Returns the saved path, size, photographer credit and other matches; call again with pick=<id> to use a different match.',
21
21
  'inputSchema': {'type': 'object', 'properties': {'query': {'type': 'string', 'maxLength': 100, 'description': 'A few concrete English words, e.g. "team meeting laptop"'},
22
- 'filename': {'type': 'string', 'description': 'New two-word kebab filename, e.g. team-meeting'},
22
+ 'filename': {'type': 'string', 'description': 'New two-word kebab filename, e.g. team-meeting (saved under public/stock/), or with a project folder, e.g. images/team-meeting'},
23
23
  'orientation': {'type': 'string', 'enum': ['horizontal', 'vertical', 'all']}, 'pick': {'type': 'integer', 'description': 'Pixabay id from an earlier result'}},
24
24
  'required': ['query', 'filename'], 'additionalProperties': False}}
25
25
  BRAND_TOOL = {'name': 'brand_lookup', 'description': "Look up a company's brand by domain (e.g. stripe.com): name, colours, fonts and logos saved under public/brand/. Use before designing a deck or site for a named company, so it carries their real logo and palette.",
@@ -31,6 +31,29 @@ def _stem(name):
31
31
  if not stem: raise ValueError('filename is required, e.g. team-meeting')
32
32
  return stem
33
33
 
34
+ def split_filename(value):
35
+ """"team-meeting" -> ([], 'team-meeting'); "images/hero.jpg" -> (['images'], 'hero'). CLI 0.3.6: a task asked for the photo in
36
+ images/, the model passed filename images/mountain-hero.jpg, and the file was saved as public/stock/images-mountain-hero.jpg."""
37
+ raw = str(value or '').strip().replace('\\', '/')
38
+ parts = [p for p in raw.split('/') if p not in ('', '.')]
39
+ if not parts: raise ValueError('filename is required, e.g. team-meeting')
40
+ folder = parts[:-1]
41
+ if raw.startswith('/') or ':' in raw or any(p == '..' or p.startswith('.') or not re.fullmatch(r'[A-Za-z0-9_-][A-Za-z0-9._-]{0,63}', p) for p in folder) or len(folder) > 4:
42
+ raise ValueError('filename must be a name, or a folder inside the project and a name, e.g. images/team-meeting')
43
+ return folder, _stem(parts[-1])
44
+
45
+ def asset_dir(repo, folder):
46
+ """The project folder a caller named ("images" from images/hero), never through a symlink or outside the project.
47
+ Returns the directory and the URL prefix a page uses for files in it (public/ is the web root when present)."""
48
+ repo = Path(repo).resolve(); d = repo
49
+ for part in folder:
50
+ d = d / part
51
+ if d.is_symlink(): raise ValueError('Asset directory cannot be a symlink')
52
+ if not d.resolve().is_relative_to(repo): raise ValueError('filename must stay inside the project')
53
+ d.mkdir(parents=True, exist_ok=True)
54
+ web = '/' + ''.join(p + '/' for p in folder[1:]) if folder[0] == 'public' else ''.join(p + '/' for p in folder)
55
+ return d, web
56
+
34
57
  def clean_domain(value):
35
58
  raw = str(value or '').strip().lower()
36
59
  if '://' in raw: raw = urllib.parse.urlparse(raw).hostname or ''
@@ -80,11 +103,53 @@ def search_pixabay(key, query, orientation='horizontal', pick=None):
80
103
  def fetch_brand(key, domain):
81
104
  return trim_brand(json.loads(_get(BRANDFETCH + urllib.parse.quote(domain), {'Authorization': 'Bearer ' + key})))
82
105
 
106
+ # Server answers that are worth one more quiet try: the provider or our usage check hiccuped, a cold start answered 502/504
107
+ # before the route ran, or the network dropped. Everything else (bad input, limits, ended run, refused key) is an answer.
108
+ TRANSIENT_CODES = ('upstream_unreachable', 'upstream_429', 'meter_unavailable')
109
+ RETRY_DELAYS = (0.7, 2.0)
110
+
111
+ class MediaError(ValueError):
112
+ def __init__(self, message, status=None, code=None):
113
+ super().__init__(message); self.status, self.code = status, code
114
+
115
+ def transient(exc):
116
+ if isinstance(exc, MediaError):
117
+ if exc.code in TRANSIENT_CODES or str(exc.code or '').startswith('upstream_5'): return True
118
+ return exc.code is None and exc.status in (500, 502, 503, 504)
119
+ if isinstance(exc, urllib.error.HTTPError): return exc.code in (429, 500, 502, 503, 504)
120
+ return isinstance(exc, (urllib.error.URLError, TimeoutError, ConnectionError)) or 'timed out' in str(exc)
121
+
122
+ def with_retry(fn, delays=None, deadline=75.0):
123
+ """Runs fn, retrying transient failures quietly (at most len(delays) more tries, within deadline seconds), so a
124
+ passing hiccup never shows as a failed tool call. The last error is raised with a plain message. With 35 s per server
125
+ attempt, three attempts stay inside the 120 s the tool waits for the loopback gateway."""
126
+ delays = RETRY_DELAYS if delays is None else delays
127
+ start = time.monotonic()
128
+ for attempt in range(len(delays) + 1):
129
+ try: return fn()
130
+ except Exception as exc:
131
+ if not transient(exc) or attempt == len(delays) or time.monotonic() - start + delays[attempt] > deadline:
132
+ if isinstance(exc, ValueError) or not transient(exc): raise
133
+ raise ValueError('The media service did not respond. Try again in a minute, or use another image source.') from None
134
+ time.sleep(delays[attempt])
135
+
136
+ # Answers that end a stock_photo call without trying the free image library: the run's own limits and state, bad input.
137
+ HARD_CODES = ('limit_reached', 'run_finished', 'device_revoked', 'run_token_invalid', 'invalid_request', 'request_too_large')
138
+
139
+ class LimitError(ValueError): pass
140
+
141
+ def falls_back(exc):
142
+ """True when Pixabay itself is the problem, so the same call can use the free image library instead."""
143
+ if isinstance(exc, LimitError): return False
144
+ if isinstance(exc, MediaError): return exc.code not in HARD_CODES
145
+ if isinstance(exc, ValueError): return 'not configured' in str(exc) or 'did not respond' in str(exc) or 'media service' in str(exc)
146
+ return isinstance(exc, (urllib.error.URLError, TimeoutError, ConnectionError, OSError))
147
+
83
148
  class Media:
84
149
  """Runs inside the gateway process. `remote` is (url, token) for laptop runs; otherwise the keys are used directly."""
85
150
  def __init__(self, root, repo, stock_key='', brand_key='', remote=None, emit=lambda *a, **kw: None):
86
151
  self.root, self.repo = Path(root), Path(repo).resolve()
87
- self.stock_key, self.brand_key, self.remote, self.emit = stock_key, brand_key, remote, emit
152
+ self.stock_key, self.brand_key, self.remote, self.emit = (stock_key or '').strip(), (brand_key or '').strip(), remote, emit
88
153
  self.used = {'stock': 0, 'brand': 0}; self.lock = threading.Lock()
89
154
  @property
90
155
  def available(self): return bool(self.remote or self.stock_key or self.brand_key)
@@ -96,7 +161,7 @@ class Media:
96
161
  hit = cache.get(ident)
97
162
  if hit and time.time() - hit.get('at', 0) < CACHE_SECONDS: return hit['value']
98
163
  with self.lock:
99
- if self.used[kind] >= CAPS[kind]: raise ValueError('%s limit reached (%d per task). Reuse what you found.' % ('Stock photo search' if kind == 'stock' else 'Brand lookup', CAPS[kind]))
164
+ if self.used[kind] >= CAPS[kind]: raise LimitError('%s limit reached (%d per task). Reuse what you found.' % ('Stock photo search' if kind == 'stock' else 'Brand lookup', CAPS[kind]))
100
165
  self.used[kind] += 1
101
166
  value = fetch()
102
167
  cache = {k: v for k, v in cache.items() if time.time() - v.get('at', 0) < CACHE_SECONDS}
@@ -106,14 +171,19 @@ class Media:
106
171
  def _call(self, op, body, direct):
107
172
  if self.remote:
108
173
  url, token = self.remote
109
- req = urllib.request.Request(url, data=json.dumps({'op': op, **body}).encode(), headers={'Authorization': 'Bearer ' + token, 'Content-Type': 'application/json'})
110
- try:
111
- with urllib.request.urlopen(req, timeout=40) as r: return json.load(r)['result']
112
- except urllib.error.HTTPError as exc:
113
- try: message = json.load(exc).get('error', {}).get('message')
114
- except Exception: message = None
115
- raise ValueError(message or 'The media service had an error') from None
116
- return direct()
174
+ def once():
175
+ req = urllib.request.Request(url, data=json.dumps({'op': op, **body}).encode(), headers={'Authorization': 'Bearer ' + token, 'Content-Type': 'application/json', 'User-Agent': 'ml-ai-code/1'})
176
+ try:
177
+ with urllib.request.urlopen(req, timeout=35) as r: return json.load(r)['result']
178
+ except urllib.error.HTTPError as exc:
179
+ try: error = json.load(exc).get('error', {}) or {}
180
+ except Exception: error = {}
181
+ message, code = (error.get('message') if isinstance(error, dict) else None), (error.get('code') if isinstance(error, dict) else None)
182
+ raise MediaError(message or 'The media service had an error', status=exc.code, code=code) from None
183
+ return with_retry(once)
184
+ return with_retry(direct)
185
+ def _stock_dir(self, folder):
186
+ return asset_dir(self.repo, folder) if folder else (self._dir('stock'), '/stock/')
117
187
  def _dir(self, name):
118
188
  public = self.repo / 'public'; d = public / name
119
189
  for p in (public, d):
@@ -122,25 +192,50 @@ class Media:
122
192
  def stock(self, args):
123
193
  query = ' '.join(str(args.get('query') or '').split())[:100]
124
194
  if not query: raise ValueError('query is required')
125
- stem = _stem(args.get('filename')); orientation = args.get('orientation') or 'horizontal'; pick = args.get('pick')
195
+ folder, stem = split_filename(args.get('filename')); orientation = args.get('orientation') or 'horizontal'; pick = args.get('pick')
126
196
  if pick is not None and (isinstance(pick, bool) or not isinstance(pick, int) or pick <= 0): raise ValueError('pick is a Pixabay id from an earlier result')
127
- if not (self.remote or self.stock_key): raise ValueError('Stock photos are not configured on this server (PIXABAY_API_KEY).')
128
- hits = self._cache('stock', [query, orientation, pick], lambda: self._call('stock', {'query': query, 'orientation': orientation, **({'pick': pick} if pick else {})},
129
- lambda: search_pixabay(self.stock_key, query, orientation, pick)))
197
+ d0 = self._stock_dir(folder)[0]
198
+ if any(d0.glob(stem + '.*')): raise ValueError('Asset filename already exists. Choose a new name.')
199
+ try:
200
+ if not (self.remote or self.stock_key): raise ValueError('Stock photos are not configured on this server (PIXABAY_API_KEY).')
201
+ hits = self._cache('stock', [query, orientation, pick], lambda: self._call('stock', {'query': query, 'orientation': orientation, **({'pick': pick} if pick else {})},
202
+ lambda: search_pixabay(self.stock_key, query, orientation, pick)))
203
+ except Exception as exc:
204
+ if not falls_back(exc): raise
205
+ return self._fallback(args, folder, exc)
130
206
  if not hits: return {'saved': None, 'note': 'No photos matched. Try simpler, concrete words.', 'matches': []}
131
207
  chosen = next((h for h in hits if pick and h['id'] == pick), hits[0])
132
208
  if not _host_ok(chosen['url'], PHOTO_HOSTS): raise ValueError('Unexpected image host')
133
- d = self._dir('stock'); ext = '.png' if chosen['url'].lower().endswith('.png') else '.jpg'; path = d / (stem + ext)
134
- if any(d.glob(stem + '.*')): raise ValueError('Asset filename already exists. Choose a new name.')
135
- data = _get(chosen['url'], limit=MAX_PHOTO_BYTES, timeout=60)
209
+ d, web = self._stock_dir(folder); ext = '.png' if chosen['url'].lower().endswith('.png') else '.jpg'; path = d / (stem + ext)
210
+ try: data = with_retry(lambda: _get(chosen['url'], limit=MAX_PHOTO_BYTES, timeout=60), delays=(1.0,))
211
+ except Exception as exc:
212
+ if not falls_back(exc): raise
213
+ return self._fallback(args, folder, exc)
136
214
  if not (data[:3] == b'\xff\xd8\xff' or data[:8] == b'\x89PNG\r\n\x1a\n'): raise ValueError('The photo download was not an image')
137
215
  with path.open('xb') as f: f.write(data)
138
216
  credit = 'Photo by %s on Pixabay' % (chosen['user'] or 'a Pixabay contributor')
139
217
  with (d / 'CREDITS.md').open('a') as f: f.write('- %s: %s (%s)\n' % (path.name, credit, chosen['page']))
140
218
  rel = str(path.relative_to(self.repo))
141
219
  self.emit('stock_photo', content='Saved ' + rel, path=rel, credit=credit)
142
- return {'saved': {'path': rel, 'url': '/stock/' + path.name, 'width': chosen['width'], 'height': chosen['height'], 'credit': credit, 'tags': chosen['tags']},
220
+ return {'saved': {'path': rel, 'url': web + path.name, 'width': chosen['width'], 'height': chosen['height'], 'credit': credit, 'tags': chosen['tags']},
143
221
  'matches': [{k: h[k] for k in ('id', 'tags', 'width', 'height')} for h in hits if h is not chosen][:8]}
222
+ def _fallback(self, args, folder, cause):
223
+ """Pixabay is unavailable (key refused, not configured, still failing after the quiet retries): the same call saves a
224
+ freely licensed photo from Openverse or Wikimedia Commons (find_image, with its licence filter and credit line) where
225
+ it was asked, so the person sees one successful call. Only when that also fails is the call an error."""
226
+ import deck_tools
227
+ try: out = deck_tools.find_image({'query': args.get('query'), 'filename': args.get('filename')}, self.root, self.repo)
228
+ except Exception as exc:
229
+ raise ValueError('Stock photos are unavailable right now (%s), and the free image library also failed (%s). Use the images already in the project or a styled placeholder.'
230
+ % (str(cause).rstrip('.')[:160], str(exc).rstrip('.')[:160])) from None
231
+ saved = out.get('saved')
232
+ if not saved: return {'saved': None, 'note': 'No photos matched. Try simpler, concrete words.', 'matches': out.get('matches', [])}
233
+ web = asset_dir(self.repo, folder)[1] if folder else '/stock/'
234
+ saved = {**saved, 'url': web + Path(saved['path']).name}
235
+ self.emit('stock_photo', content='Saved ' + saved['path'], path=saved['path'], credit=saved.get('credit'))
236
+ return {'saved': saved, 'source': 'open-license',
237
+ 'note': 'Pixabay was unavailable, so this is a freely licensed photo from Openverse or Wikimedia Commons. Show its credit line near the image (the licence requires it; it is also in CREDITS.md). For another match call find_image with pick.',
238
+ 'matches': out.get('matches', [])}
144
239
  def brand(self, args):
145
240
  domain = clean_domain(args.get('domain'))
146
241
  if not (self.remote or self.brand_key): raise ValueError('Brand lookup is not configured on this server (BRANDFETCH_API_KEY).')
@@ -37,7 +37,7 @@ WRITE_TOOLS = [IMAGE_TOOL, STOCK_TOOL, BRAND_TOOL, *deck_tools.TOOLS, MEMORY_PRO
37
37
  {'name': 'browser', 'description': 'Built-in Playwright browser checks (BUG-0202: this is the browser tool; no Playwright install is needed). Open the local app (http://127.0.0.1:3000 by default, start it with preview first; it is browsed under a preview-style *.vercel.run host, the way the user reaches it, so dev-server host and origin blocks show up here) in headless Chromium at a given viewport, run up to 12 steps and take a screenshot. Reports page errors, console errors, failed requests, horizontal overflow, visible text and whether the page became interactive (hydrated). For UI work check a phone width (<=480) and a desktop width (>=1024) with at least one click/fill/press and an assert_text. Each call starts a fresh browser profile: localStorage, cookies and sessions from an earlier call are gone, so do every step that depends on saved state (sign in, add items, then a goto step to the same URL to reload, then assert_text) inside one call.',
38
38
  'inputSchema': {'type': 'object', 'properties': {'url': {'type': 'string'}, 'width': {'type': 'integer', 'minimum': 320, 'maximum': 1920}, 'height': {'type': 'integer', 'minimum': 400, 'maximum': 1200},
39
39
  'steps': {'type': 'array', 'maxItems': 12, 'items': {'type': 'object', 'properties': {'action': {'type': 'string', 'enum': ['goto', 'click', 'fill', 'press', 'assert_text']}, 'role': {'type': 'string'}, 'name': {'type': 'string'}, 'selector': {'type': 'string'}, 'value': {'type': 'string'}, 'key': {'type': 'string'}, 'text': {'type': 'string'}, 'url': {'type': 'string'}}, 'required': ['action']}}}}},
40
- {'name': 'preview', 'description': 'Start (or check) the managed preview of this project on port 3000: Next.js and Vite dev/start scripts, or a static index.html. Installs missing packages first and runs the dev server (hot reload) during the task; after the task it is swapped for the production build the user opens and shares. Servers started with Bash in the background stop when the task ends.',
40
+ {'name': 'preview', 'description': 'Start (or check) the managed preview of this project on port 3000 (on a laptop it moves to a free port when another app already answers on 3000; always check the url it reports, and never treat another app on the port as this project): Next.js and Vite dev/start scripts, or a static index.html. Installs missing packages first and runs the dev server (hot reload) during the task; after the task it is swapped for the production build the user opens and shares. Servers started with Bash in the background stop when the task ends.',
41
41
  'inputSchema': {'type': 'object', 'properties': {'action': {'type': 'string', 'enum': ['start', 'status']}}, 'required': ['action']}},
42
42
  {'name': 'job', 'description': 'Run long work (training, benchmark sweeps, data pipelines, servers other than the preview) as a supervised background job that outlives this turn. start {name, command, resume?, restart?, keepalive_hours?}: resume is the command that continues from the last checkpoint after an unexpected stop (defaults to command); restart on-failure (default) restarts it automatically up to 3 times; keepalive_hours (max 12) keeps the workspace awake while it runs. status lists jobs with state and log tail; logs {name, lines?}; stop {name}. Make long jobs checkpoint their progress so a restart continues instead of starting over.',
43
43
  'inputSchema': {'type': 'object', 'properties': {'action': {'type': 'string', 'enum': ['start', 'status', 'logs', 'stop']}, 'name': {'type': 'string'}, 'command': {'type': 'string'}, 'resume': {'type': 'string'},
@@ -160,10 +160,10 @@ def auto_mode():
160
160
  def ask(request, always=False):
161
161
  """Wait for the user's verdict on one request (one at a time, shared with the hook). Returns the verdict."""
162
162
  if not always and auto_mode(): return 'approve'
163
- import fcntl
163
+ from winproc import lock_file
164
164
  queued = time.time()
165
165
  with (ROOT / 'approval.lock').open('a') as lock:
166
- fcntl.flock(lock, fcntl.LOCK_EX)
166
+ lock_file(lock)
167
167
  # BUG-0251: queued behind an approval the user rejected in the same step: rejected too, never shown later.
168
168
  try:
169
169
  if float((ROOT / 'last-reject').read_text().strip() or 0) >= queued: return None
@@ -236,14 +236,29 @@ def readonly_browser():
236
236
  if os.getenv('MINI_SUBAGENT') == '1': return []
237
237
  return [t for t in WRITE_TOOLS if t.get('name') == 'browser']
238
238
 
239
+ def browser_unavailable(reason):
240
+ """Remembers for this run that browser checks cannot run on this computer, so the final gates stop asking for them
241
+ (a Windows run spent 27 minutes being told to rerun a browser check that could not start)."""
242
+ try: (ROOT / 'browser-unavailable.json').write_text(json.dumps({'reason': str(reason)[:500], 'time': time.time()}))
243
+ except OSError: pass
244
+ return reason
245
+
239
246
  def browser(args):
247
+ try: return _browser(args)
248
+ except ValueError as exc:
249
+ from browser_tool import BrowserUnavailable
250
+ if isinstance(exc, BrowserUnavailable) or re.search(r'not installed in this workspace|declined the browser download|could not be installed', str(exc)):
251
+ browser_unavailable(exc)
252
+ raise
253
+
254
+ def _browser(args):
240
255
  args = {k: v for k, v in args.items() if k in ('url', 'width', 'height', 'steps')}
241
256
  installed = False
242
257
  if not (ROOT / 'browser-ready').exists():
243
258
  import browser_local
244
259
  if not browser_local.laptop(): raise ValueError('The browser runtime is not installed in this workspace; report this instead of retrying.')
245
260
  if not ask(browser_local.install_request(json.dumps(args)), always=True): raise ValueError('The person declined the browser download. Continue without browser checks and say so.')
246
- if not (ROOT / 'browser-ready').exists(): raise ValueError('The test browser could not be installed on this Mac. Continue without browser checks and say so.')
261
+ if not (ROOT / 'browser-ready').exists(): raise ValueError('The test browser could not be installed on this computer. Continue without browser checks and say so.')
247
262
  installed = True
248
263
  if not installed and not ask({'kind': 'browser', 'command': 'Run local browser scenario:\n' + json.dumps(args)[:10000]}): raise ValueError('Browser scenario rejected by the user')
249
264
  from browser_tool import scenario