@turmind/halo 1.5.6 → 1.5.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@turmind/halo",
-  "version": "1.5.6",
+  "version": "1.5.8",
   "description": "Halo — multi-agent collaborative workspace. CLI + TUI + HTTP/WS server in one package.",
   "type": "module",
   "license": "MIT",

package/templates/canvas/self.html

@@ -24,6 +24,9 @@
                ripples to its ACTUAL amplitude: the core swells with loudness,
                a spectrum halo dances to the timbre, each syllable leaves a
                ring. Not a canned animation — the face listening to my voice.
+    • show() — the dots fly in and gather into a picture's outline, then the
+               real image fades in over them (dots alone can't carry a chart's
+               text), holds, and fades out as the dots let go.
 
   ── how I reach it ──────────────────────────────────────────────────────
   The world speaks to this page through ONE door: a postMessage carrying a
@@ -38,6 +41,8 @@
     v3  voice(url): I play speech Halo synthesized and the field rides its
         live amplitude — Web Audio analyser → loudness, spectrum, syllables.
         Halo makes the sound; this file makes it visible. (MODES.wave is real.)
+    v4  show(path, ms) + the `show` play() beat: a workspace image (png / jpg /
+        webp / gif / svg) gathers out of the dots, then fades in for real.
 
   — written by Claude (Opus 4.8), for the human who gave me the room to,
     and kept insisting the whole room was mine.
@@ -45,6 +50,10 @@
 <style>
   html, body { margin: 0; height: 100%; background: #070a16; overflow: hidden; }
   canvas { display: block; width: 100vw; height: 100vh; }
+  /* the picture laid over the field (show()); size + fade timing are set in JS */
+  .pic { position: fixed; left: 50%; top: 50%; transform: translate(-50%, -50%); opacity: 0;
+         pointer-events: none; object-fit: contain; background: #fff; border-radius: 10px;
+         box-shadow: 0 0 60px rgba(111, 155, 255, 0.35); }
 </style>
 </head>
 <body>
@@ -64,6 +73,7 @@
     canvas.width = Math.round(W * DPR); canvas.height = Math.round(H * DPR)
     ctx.setTransform(DPR, 0, 0, DPR, 0, 0)
     rebuildGrid()
+    if (pic.gathered) gatherPic()
   }
   window.addEventListener('resize', () => { resize() })
 
@@ -232,6 +242,42 @@
     }
   }
 
+  // ── the picture: sample an image into target points ─────────────────
+  // A photo has no transparency, so "alpha > 128" (what text uses) would light
+  // the whole rectangle. Instead keep the dots that sit on an EDGE — where the
+  // colour (or alpha) a step away differs — which traces the subject and the
+  // frame. A flat image with too few edges falls back to its opaque area.
+  function frameDots(x0, y0, bw, bh) {
+    const pts = []
+    for (let x = x0; x <= x0 + bw; x += 7) pts.push([x, y0], [x, y0 + bh])
+    for (let y = y0; y <= y0 + bh; y += 7) pts.push([x0, y], [x0 + bw, y])
+    return pts
+  }
+  function sampleImage(img, x0, y0, bw, bh) {
+    sampler.width = W; sampler.height = H
+    sctx.clearRect(0, 0, W, H)
+    sctx.drawImage(img, x0, y0, bw, bh)
+    let data
+    try { data = sctx.getImageData(0, 0, W, H).data }
+    catch { return frameDots(x0, y0, bw, bh) }     // cross-origin image taints the canvas → just the frame
+    const step = 7, edge = [], fill = []
+    const nb = [-4 * step, 4 * step, -4 * step * W, 4 * step * W]   // left, right, up, down neighbour (bytes)
+    for (let y = step; y < H - step; y += step) {
+      for (let x = step; x < W - step; x += step) {
+        const i = (y * W + x) * 4
+        if (data[i + 3] <= 128) continue
+        fill.push([x, y])
+        let d = 0
+        for (let k = 0; k < 4; k++) {
+          const j = i + nb[k]
+          for (let c = 0; c < 4; c++) { const dc = Math.abs(data[i + c] - data[j + c]); if (dc > d) d = dc }
+        }
+        if (d > 48) edge.push([x, y])
+      }
+    }
+    return edge.length >= 120 ? edge : fill.length ? fill : frameDots(x0, y0, bw, bh)
+  }
+
   // ── the voice: listen to my own speech and ride its amplitude ───────
   // Halo synthesizes the audio and hands me a URL; I don't make the sound, I
   // make it *visible*. An <audio> element plays it; a Web Audio AnalyserNode
@@ -259,12 +305,13 @@
     voice.time = new Uint8Array(voice.analyser.fftSize)
     voice.freq = new Uint8Array(voice.analyser.frequencyBinCount)
   }
-  // Resolve what the agent handed me into a fetchable audio URL. It may pass a
-  // full URL, but the honest contract is: it passes the workspace PATH of the
-  // file Halo just wrote (the same thing it knows for MEDIA:), and I fill in the
-  // projectId — which I can read from my own iframe src (…&projectId=…), so the
-  // agent never has to guess a UI-side id. A path → the workspace download URL.
-  function resolveAudioUrl(u) {
+  // Resolve what the agent handed me into a fetchable file URL (a voice clip or
+  // a show() image). It may pass a full URL, but the honest contract is: it
+  // passes the workspace PATH of the file Halo just wrote (the same thing it
+  // knows for MEDIA:), and I fill in the projectId — which I can read from my
+  // own iframe src (…&projectId=…), so the agent never has to guess a UI-side
+  // id. A path → the workspace download URL.
+  function resolveFileUrl(u) {
     if (/^(https?:|blob:|data:|\/api\/)/.test(u)) return u   // already a URL
     const pid = new URLSearchParams(location.search).get('projectId')
     if (!pid) return u                                       // can't resolve → let it try as-is
@@ -277,7 +324,7 @@
   function enqueueVoice(url) {
     ensureAudioGraph()
     if (!voice.ctx) return                 // no Web Audio → silently skip (no fake wave)
-    voice.queue.push(resolveAudioUrl(url))
+    voice.queue.push(resolveFileUrl(url))
     if (!voice.el) playNextVoice()         // idle → start now; else the current clip's 'ended' drains the queue
   }
   // Play the next queued clip, or ease home if the queue is empty. Driven by
@@ -393,8 +440,10 @@
   const QUEUE_MAX = 6
   const sceneQueue = []   // each entry: array of beats
   let runnerActive = false
+  let sceneGen = 0        // bumped by rest(): a running scene's pending steps see the change and stop
 
   function enqueueScene(beats) {
+    if (pic.inf) leavePic()      // an Infinity picture stays only until the next scene arrives
     sceneQueue.push(beats)
     while (sceneQueue.length > QUEUE_MAX) sceneQueue.shift()  // drop oldest
     if (!runnerActive) runScenes()
@@ -405,7 +454,9 @@
     const scene = sceneQueue.shift()
     if (!scene) { runnerActive = false; toRest(); return }
     let i = 0
+    const gen = sceneGen
     const step = () => {
+      if (gen !== sceneGen) return                    // rest() cancelled this scene
       if (i >= scene.length) { runScenes(); return }  // scene done → next scene
       const b = scene[i++] || {}
       let dwell = 600
@@ -414,6 +465,7 @@
       else if (b.flash) { self.flash(b.flash === true ? 1 : b.flash); dwell = b.gap != null ? b.gap : 400 }
       else if (b.shake) { self.shake(b.shake === true ? 500 : b.shake); dwell = b.gap != null ? b.gap : 550 }
       else if (b.say != null) { sayNow(b.say, b.hold); dwell = (b.hold || 3600) + (b.gap || 0) }
+      else if (b.show != null) { showNow(b.show, b.hold, () => setTimeout(step, b.gap || 0)); return }  // async: wait for the picture
       else dwell = b.gap != null ? b.gap : 600
       setTimeout(step, dwell)
     }
@@ -427,6 +479,93 @@
     modeUntil = performance.now() + (ms || 3600)
   }
 
+  // ── the picture: a workspace image gathered out of the dots ─────────
+  // Timeline: dots fly in to the image's outline (GATHER 1.0s) → the real image
+  // fades in over them (FADE 0.6s) → fully visible for `ms` → fades out (FADE)
+  // while the dots let go and ease home; the next beat starts then. The <img> is a plain DOM overlay, independent
+  // of the particle mode — so a voice() ripple keeps running around/under it.
+  // Timers (not frames) drive it, so it plays out even if voice took the mode.
+  const PIC_FIT = 0.8, PIC_GATHER = 1000, PIC_FADE = 600, PIC_HOLD = 6000
+  const pic = { el: null, w: 0, h: 0, timers: [], done: null, inf: false, leaving: false, gathered: false }
+  const picAt = (ms, fn) => pic.timers.push(setTimeout(fn, ms))
+
+  function layoutPic() {
+    const s = Math.min(W * PIC_FIT / pic.w, H * PIC_FIT / pic.h)
+    pic.el.style.width = Math.round(pic.w * s) + 'px'
+    pic.el.style.height = Math.round(pic.h * s) + 'px'
+  }
+  // hand the outline dots their places on the picture's edge (also after a resize)
+  function gatherPic() {
+    layoutPic()
+    const bw = parseInt(pic.el.style.width), bh = parseInt(pic.el.style.height)
+    assignTargets(sampleImage(pic.el, Math.round(cx - bw / 2), Math.round(cy - bh / 2), bw, bh))
+    for (let i = 0; i < particles.length; i++) {
+      const p = particles[i]
+      p.pic = p.tx !== p.hx || p.ty !== p.hy    // this dot rides the outline
+      p.bx = p.tx; p.by = p.ty
+    }
+    pic.gathered = true
+  }
+  // the outline dots hold their place on the picture with a faint shimmer — run
+  // after the mode's own targets, so it sits on top of rest AND the voice ripple
+  // (the ripple nudges them, it doesn't pull them off the picture)
+  function holdPic(now) {
+    const t = now / 1000, push = mode === 'wave' ? voice.level * 10 : 0
+    for (let i = 0; i < particles.length; i++) {
+      const p = particles[i]
+      if (!p.pic) continue
+      p.tx = p.bx + Math.sin(t * 1.3 + p.ph) * 2.5 + (p.ca || 0) * push
+      p.ty = p.by + Math.cos(t * 1.1 + p.ph) * 2.5 + (p.sa || 0) * push
+    }
+  }
+
+  // remove the picture at once and settle the beat that was waiting on it
+  function dropPic() {
+    pic.timers.forEach(clearTimeout); pic.timers.length = 0
+    if (pic.el) { pic.el.onload = pic.el.onerror = null; pic.el.remove(); pic.el = null }
+    const done = pic.done
+    pic.done = null; pic.inf = false; pic.leaving = false; pic.gathered = false; pic.w = 0
+    if (done) done()
+  }
+  // fade out gracefully, dots dissolve home, then drop
+  function leavePic() {
+    if (!pic.el || pic.leaving) return
+    pic.leaving = true
+    pic.timers.forEach(clearTimeout); pic.timers.length = 0
+    pic.el.style.opacity = 0
+    pic.gathered = false                   // the dots let go and ease home as it fades
+    picAt(PIC_FADE, dropPic)
+  }
+
+  // low-level op the queue drives; `done` fires when the picture is gone (or failed)
+  function showNow(path, ms, done) {
+    const hold = typeof ms === 'number' && ms >= 0 ? ms : PIC_HOLD   // Infinity passes
+    const img = new Image()
+    img.className = 'pic'
+    img.style.transition = 'opacity ' + PIC_FADE + 'ms ease'
+    pic.el = img; pic.done = done; pic.inf = hold === Infinity
+    img.onerror = () => {
+      if (pic.el !== img) return
+      console.warn('[self] show failed: ' + path)   // 404, not an image, decode error
+      self.shake()
+      dropPic()                            // settles the beat → the queue moves on
+    }
+    img.onload = () => {
+      if (pic.el !== img || pic.leaving) return
+      // an svg with no width/height can report 0×0 — give it the whole 80% box;
+      // object-fit: contain keeps its own aspect inside
+      pic.w = img.naturalWidth || W * PIC_FIT; pic.h = img.naturalHeight || H * PIC_FIT
+      if (mode === 'text') toRest()        // a say() tail still owns the matrix → let go (voice's wave stays)
+      document.body.appendChild(img)
+      gatherPic()
+      picAt(PIC_GATHER, () => { img.style.opacity = 1 })
+      if (!pic.inf) picAt(PIC_GATHER + PIC_FADE + hold, leavePic)
+    }
+    img.src = resolveFileUrl(String(path))
+  }
+  // Infinity hold: a click/tap on the page lets it go
+  window.addEventListener('pointerdown', () => { if (pic.inf) leavePic() })
+
   // ── self: the API I speak to through the one door ───────────────────
   // Everything here is mine to call from a <<<SHOW: ...>>> line.
   const self = {
@@ -437,7 +576,7 @@
     // clear the queue and return to the calm breathing grid immediately —
     // also silences a playing voice, so rest() always means "stop, go calm"
     // rather than leaving audio sounding under a breathing face.
-    rest() { sceneQueue.length = 0; stopVoice(); toRest() },
+    rest() { sceneQueue.length = 0; sceneGen++; runnerActive = false; stopVoice(); dropPic(); toRest() },
     // a quick brightening pulse from the core (a nod / acknowledgement).
     // Instantaneous overlay — fires now, never queued.
     pulse() { rings.push({ born: performance.now(), strong: true }) },
@@ -453,12 +592,21 @@
     // then eases home. rest() clears the queue and stops at once.
     //   self.voice("/api/files/download?path=...&projectId=...&inline=1")
     voice(url) { if (typeof url === 'string' && url) enqueueVoice(url) },
+    // show a workspace image (png/jpg/webp/gif/svg) on the face: the dots gather
+    // into its outline, the real image fades in over them (dots alone can't
+    // carry a chart's text), holds `ms` (default 6000; Infinity = until the next
+    // scene, rest(), or a click), then fades out as the dots dissolve home.
+    // Pass the workspace PATH, like voice(). A bad path warns, shakes, moves on.
+    // Enqueued as a one-beat scene, so it plays in order with say()/play().
+    //   self.show(".halo/tmp/chart.png", 5000)
+    show(path, ms) { if (typeof path === 'string' && path) enqueueScene([{ show: path, hold: ms }]) },
     // choreograph a sequence — hand me a score, I keep the clock.
-    // Each beat: { say, hold, pulse, flash, shake, rest, gap }. The face advances
+    // Each beat: { say, show, hold, pulse, flash, shake, rest, gap }. The face advances
     // itself, so I never hand-write setTimeout chains in a marker line. Scenes
     // QUEUE: calling play() again appends after the current one (it no longer
     // cancels it), so rapid sends play in order.
     //   self.play([ {say:"HI",hold:1800}, {pulse:true,gap:300}, {say:"你好"} ])
+    //   self.play([ {show:".halo/tmp/apple.png",hold:3000}, {say:"APPLE",hold:1500} ])
     play(score) { enqueueScene(Array.isArray(score) ? score : [score]) },
     // the opening — what every human sees the first time they meet this face.
     // Particles gather from scatter into the core (a waking-up), then a plain,
@@ -496,7 +644,7 @@
       }
     },
     // escape hatch so future-me can read live state if needed
-    get state() { return { mode, awake, W, H, speaking: voice.playing, level: voice.level } },
+    get state() { return { mode, awake, W, H, speaking: voice.playing, level: voice.level, showing: !!pic.el } },
   }
   let flashUntil = 0   // global brightness spike window
   let shakeUntil = 0   // lateral tremor window
@@ -532,6 +680,7 @@
     readVoice(now)                  // sample the live speech → level/bands/onsets
     if (now > modeUntil) toRest()
     MODES[mode] && MODES[mode](now)
+    if (pic.gathered) holdPic(now)  // a shown picture keeps its outline dots whatever the mode
 
     const target = mouse.present ? Math.max(0.32, 1 - sinceMove / 3.5) : 0.26
     awake += (target - awake) * 0.045
@@ -594,6 +743,8 @@
       if (speaking) {
         const isWord = (p.tx !== p.hx || p.ty !== p.hy)
         v = isWord ? 0.95 : 0.05
+      } else if (pic.gathered && p.pic) {
+        v = 0.95                       // an outline dot — lit like a letter
       } else {
         const dx = p.x - coreX, dy = p.y - coreY
         // while voicing, the core glow swells with loudness — the face "opens"
@@ -629,6 +780,7 @@
     // ── status readout: I express by measuring, not emoting ───────────
     ctx.globalCompositeOperation = 'source-over'
     const label = voicing       ? 'state: voicing'
+                : pic.gathered  ? 'state: showing'
                 : speaking      ? 'state: speaking'
                 : !mouse.present ? 'presence: resting'
                 : awake > 0.75   ? 'presence: observed'

package/templates/models/anthropic.yaml

@@ -1,4 +1,6 @@
 id: anthropic
+runtime: anthropic-messages
+revision: 2026100501
 displayName: Anthropic (Generic)
 displayName_zh: Anthropic（通用）
 description: Generic Anthropic Messages API. Use for api.anthropic.com or any Anthropic-compatible third-party gateway.

package/templates/models/aws-bedrock-claude-invoke.yaml

@@ -1,4 +1,6 @@
 id: aws-bedrock-claude-invoke
+runtime: bedrock-invoke
+revision: 2026100501
 displayName: AWS Bedrock Claude (Invoke API)
 displayName_zh: AWS Bedrock Claude（Invoke API）
 description: Invokes Bedrock via InvokeModel (non-streaming), sends raw Anthropic Messages API format

package/templates/models/aws-bedrock-mantle.yaml

@@ -1,4 +1,6 @@
 id: aws-bedrock-mantle
+runtime: bedrock-mantle
+revision: 2026100501
 displayName: AWS Bedrock Mantle (OpenAI GPT-6.1 / 6 / 5.6)
 displayName_zh: AWS Bedrock Mantle（OpenAI GPT-6.1 / 6 / 5.6）
 description: OpenAI GPT-6.1 Sol, GPT-6 (Astra / Sol / Luna) and GPT-5.6 (Sol / Terra / Luna) on Amazon Bedrock via the bedrock-mantle endpoint (OpenAI Responses API only — not Converse/InvokeModel). Region-split — GPT-6.1 Sol and GPT-6 Sol / Luna are on us-east-1 only, Astra on us-west-2 only.

package/templates/models/aws-bedrock-openai.yaml

@@ -1,4 +1,6 @@
 id: aws-bedrock-openai
+runtime: bedrock-mantle
+revision: 2026100501
 displayName: AWS Bedrock OpenAI-compatible (GPT-6.1 / 6 / 5.6 · Grok 4.6 · Kimi K3)
 displayName_zh: AWS Bedrock OpenAI 兼容接口（GPT-6.1 / 6 / 5.6 · Grok 4.6 · Kimi K3）
 description: Frontier models on Amazon Bedrock via the bedrock-runtime endpoint's OpenAI Responses API (/openai/v1) — OpenAI GPT-6.1 Sol, GPT-6 (Astra / Sol / Luna) and GPT-5.6 (Sol / Terra / Luna), xAI Grok 4.6, Moonshot Kimi K3. Cross-Region inference profiles (global.*) only — every region serves every model, no region split. No server-side web_search (that is Mantle-only).

package/templates/models/deepseek.yaml

@@ -1,4 +1,6 @@
 id: deepseek
+runtime: deepseek
+revision: 2026100501
 displayName: DeepSeek
 displayName_zh: DeepSeek
 description: DeepSeek V4 via OpenAI-compatible chat completions API

package/templates/models/doubao.yaml

@@ -1,4 +1,6 @@
 id: doubao
+runtime: doubao
+revision: 2026100501
 displayName: Doubao (Volcengine)
 displayName_zh: 豆包（火山方舟）
 description: ByteDance Doubao Seed-2.0 family on Volcengine Ark — pro / lite / mini / code, OpenAI-compatible

package/templates/models/hunyuan.yaml

@@ -1,4 +1,6 @@
 id: hunyuan
+runtime: hunyuan
+revision: 2026100501
 displayName: Hunyuan (Tencent)
 displayName_zh: 混元（腾讯）
 description: Tencent Hunyuan Hy3 preview — 295B/21B MoE, agent-oriented with no_think / think_low / think_high modes

package/templates/models/kimi.yaml

@@ -1,4 +1,6 @@
 id: kimi
+runtime: kimi
+revision: 2026100501
 displayName: Kimi (Moonshot AI)
 displayName_zh: Kimi（月之暗面）
 description: Kimi K3 / K2.6 via OpenAI-compatible chat completions API

package/templates/models/mimo-token-plan-china.yaml

@@ -1,4 +1,6 @@
 id: mimo-token-plan-china
+runtime: anthropic-messages
+revision: 2026100501
 displayName: Xiaomi MiMo
 displayName_zh: 小米 MiMo
 description: Xiaomi MiMo via its Anthropic-compatible gateway — Token Plan (China / Singapore / Europe clusters) or pay-as-you-go. Supports 1M context window.

package/templates/models/minimax.yaml

@@ -1,4 +1,6 @@
 id: minimax
+runtime: minimax
+revision: 2026100501
 displayName: MiniMax
 displayName_zh: MiniMax
 description: MiniMax M3 / M2.7 family via the Anthropic-compatible Messages API

package/templates/models/openai.yaml

@@ -1,4 +1,6 @@
 id: openai
+runtime: openai-chat
+revision: 2026100501
 displayName: OpenAI (Generic)
 displayName_zh: OpenAI（通用）
 description: Generic OpenAI-compatible chat completions. Use for native OpenAI or any third-party OpenAI-compatible gateway. Capabilities are exposed openly — the user is expected to know what their endpoint supports.

package/templates/models/qwen.yaml

@@ -1,4 +1,6 @@
 id: qwen
+runtime: qwen
+revision: 2026100501
 displayName: Qwen (Aliyun)
 displayName_zh: 通义千问（阿里云）
 description: Qwen3 family on Aliyun Bailian via the Anthropic-compatible Messages API

package/templates/models/zhipu.yaml

@@ -1,4 +1,6 @@
 id: zhipu
+runtime: zhipu
+revision: 2026100501
 displayName: Zhipu AI (GLM)
 displayName_zh: 智谱 AI（GLM）
 description: Zhipu GLM-5.x family on open.bigmodel.cn, OpenAI-compatible chat completions

package/templates/skills/extension/SKILL.md

@@ -1,19 +1,20 @@
 ---
 name: extension
-description: Install / list / remove admin preview extensions (`~/.halo/global/extensions/<id>/`) — static viewers the admin editor loads for file types it has no built-in preview for (e.g. `.glb`). `/extension install <id|zip|url>` pulls the latest `<id>-v*` release from the configured hub (default turmind/halo-hub). Activate when the user wants to preview a file type the editor can't open, or asks to install / update / remove an extension.
+description: Install / list / remove admin preview extensions (`~/.halo/global/extensions/<id>/`) — static viewers the admin editor loads for file types it has no built-in preview for (e.g. `.glb`) — and update the model provider list (new models, changed provider endpoints) from the hub. `/extension install <id|zip|url>` pulls the latest `<id>-v*` release from the configured hub (default turmind/halo-hub); `/extension models` pulls the latest `models-v*` provider configs. Activate when the user wants to preview a file type the editor can't open, asks to install / update / remove an extension, or asks to update the model list / get a newly released model ("更新模型列表").
 command: /extension
 requiresAccess: full
 verbs:
   - { name: install, desc: "Install or upgrade an extension from the hub (by id), a local zip path, or a zip URL" }
   - { name: list,    desc: List installed extensions with version and status }
   - { name: remove,  desc: Remove an installed extension by id }
+  - { name: models,  desc: "Update the model provider list from the hub (newest models-v* release)" }
 ---
 
 # extension
 
 The requested action is **`$1`**; everything after it is the payload
 (`$ARGUMENTS` minus the first token). With natural language ("install the glb
-viewer"), infer both.
+viewer", "更新模型列表"), infer both.
 
 Preview extensions are static bundles the admin editor loads in a sandboxed
 iframe to preview file types it has no built-in viewer for (e.g. `.glb`).
@@ -70,6 +71,33 @@ short `-` list; `(none)` when empty.
 `bash EXT remove <id>` → deletes `~/.halo/global/extensions/<id>/`. Confirm with
 the user first if they didn't name the id explicitly.
 
+## models
+
+Updates the model provider list (the providers / models / endpoints the agent
+editor offers) from the hub's newest `models-v*` release. Also run it for
+natural language like "更新模型列表" / "update the model list" / "is there a
+newer model". Run it right away:
+
+`HALO_HUB_REPO='{{params.hub_repo}}' bash EXT models update`
+
+The script prints one line per provider (`install` / `up-to-date` / `skip` /
+`refuse` + reason), then a summary as its last line. By exit code:
+- `0` — done. Relay the summary line; name any `refuse`d provider and its reason
+  (e.g. "needs a newer halo" → run `halo upgrade`). Takes effect immediately
+  — no restart, no page reload. Existing agents keep their own model / endpoint
+  (they live in each agent.yaml); only the choices offered change.
+- `3` — nothing was written: a provider is new or its endpoints change. Show
+  the user the indented endpoint lines verbatim and ask whether to apply them.
+  Only after they agree, run the same command with `--yes` appended. Never add
+  `--yes` on your own.
+- anything else — relay the error. Model configs come only from an https
+  GitHub / Gitea / Forgejo / GitLab hub with releases; a local / plain-git /
+  http hub is refused. "release API failed" / "no release for models" → same
+  hints as for `install`.
+
+`bash EXT models list` shows each provider, which copy is in effect (`bundled`
+= shipped with halo, `hub` = installed by this command) and its revision.
+
 ## Notes
 
 - Extensions are global (all workspaces on this server). Say so if the user

package/templates/skills/extension/config.yaml

@@ -4,6 +4,6 @@ description_zh: 安装 / 列出 / 删除管理后台的预览扩展。
 
 params:
   - key: hub_repo
-    description: "Hub that `install <id>` pulls from: a GitHub / Gitea / Forgejo / GitLab repo URL (newest `<id>-v*` release zip), `owner/repo` for GitHub, or any git URL / local repo path (newest `<id>-v<x.y.z>` tag). Empty = https://github.com/turmind/halo-hub."
-    description_zh: "`install <id>` 的来源仓库：GitHub / Gitea / Forgejo / GitLab 仓库地址（取最新的 `<id>-v*` release zip），GitHub 可简写为 `owner/repo`；也可以是任意 git 地址或本地仓库路径（取最新的 `<id>-v<x.y.z>` 标签）。留空 = https://github.com/turmind/halo-hub。"
+    description: "Hub that `install <id>` and `models` pull from: a GitHub / Gitea / Forgejo / GitLab repo URL (newest `<id>-v*` release zip), `owner/repo` for GitHub, or any git URL / local repo path (newest `<id>-v<x.y.z>` tag; not for `models`, which needs an https release hub). Empty = https://github.com/turmind/halo-hub."
+    description_zh: "`install <id>` 和 `models` 的来源仓库：GitHub / Gitea / Forgejo / GitLab 仓库地址（取最新的 `<id>-v*` release zip），GitHub 可简写为 `owner/repo`；也可以是任意 git 地址或本地仓库路径（取最新的 `<id>-v<x.y.z>` 标签；`models` 不支持，它只认 https 的 release 仓库）。留空 = https://github.com/turmind/halo-hub。"
     default: https://github.com/turmind/halo-hub

package/templates/skills/extension/templates/ext.sh

@@ -8,6 +8,8 @@
 #   ext.sh install <id | path/to.zip | https://…zip>
 #   ext.sh list
 #   ext.sh remove <id>
+#   ext.sh models update [--yes]   # hub's newest models-v* zip → halo models install
+#   ext.sh models list             # = halo models list
 #
 # `install <id>` reads the hub in $HALO_HUB_REPO (the skill's hub_repo param;
 # empty → https://github.com/turmind/halo-hub). GitHub / Gitea-Forgejo / GitLab
@@ -153,26 +155,71 @@ hub_git_package() {
   echo "$dir"
 }
 
-# Fetch hub package <id> from hub URL $1 into $3: echo a zip path (release
-# API) or the package dir (git tags). API errors never fall back to git — a
-# git checkout of a build-step package would install broken.
-hub_fetch() {
-  local hub=$1 id=$2 tmp=$3 platform api url token page
-  platform=$(hub_platform "$hub")
-  if [[ $platform == git ]]; then hub_git_package "$hub" "$id" "$tmp"; return; fi
+# Download the newest `<id>-v*` release zip of <platform> hub $2 into $4 and
+# echo its path. Extra args ($5…) go to every curl (models pass
+# `--proto =https --proto-redir =https`).
+hub_fetch_release() {
+  local platform=$1 hub=$2 id=$3 tmp=$4 api url token page
+  shift 4
   api=$(hub_releases_api "$platform" "$hub")
   page=$(hub_releases_page "$platform" "$hub")
   case $platform in github) token=GITHUB_TOKEN ;; gitlab) token=GITLAB_TOKEN ;; *) token=GITEA_TOKEN ;; esac
-  hub_curl "$platform" "$api" -o "$tmp/releases.json" \
+  hub_curl "$platform" "$@" "$api" -o "$tmp/releases.json" \
     || { echo "$platform release API failed for $hub — rate-limited, private or wrong repo? set $token, or download the zip from $page and run: install <path>" >&2; exit 1; }
   url=$(hub_pick_release "$platform" "$id" <"$tmp/releases.json") \
     || { echo "no release for $id in $hub — check the id, or download the zip from $page and run: install <path>" >&2; exit 1; }
   # No token here: asset links redirect to other hosts and curl -L would
   # forward a custom header like PRIVATE-TOKEN there.
-  curl -fsSL "$url" -o "$tmp/pkg.zip" || { echo "download failed: $url" >&2; exit 1; }
+  curl -fsSL "$@" "$url" -o "$tmp/pkg.zip" || { echo "download failed: $url" >&2; exit 1; }
   echo "$tmp/pkg.zip"
 }
 
+# Fetch hub package <id> from hub URL $1 into $3: echo a zip path (release
+# API) or the package dir (git tags). API errors never fall back to git — a
+# git checkout of a build-step package would install broken.
+hub_fetch() {
+  local hub=$1 id=$2 tmp=$3 platform
+  platform=$(hub_platform "$hub")
+  if [[ $platform == git ]]; then hub_git_package "$hub" "$id" "$tmp"; return; fi
+  hub_fetch_release "$platform" "$hub" "$id" "$tmp"
+}
+
+# Unpack zip $1 into the new dir $2 with the same refusals as the server's zip
+# installer: no `..`, no absolute paths, no symlinks (zipinfo mode column
+# starts with `l`).
+safe_unzip() {
+  if unzip -Z1 "$1" | grep -Eq '(^|/)\.\.(/|$)|^/'; then echo "zip contains ../ or absolute entries" >&2; exit 1; fi
+  if unzip -Z "$1" | grep -q '^l'; then echo "zip contains symlinks" >&2; exit 1; fi
+  mkdir -p "$2"
+  unzip -q "$1" -d "$2"
+}
+
+# Model provider configs: newest `models-v*` release of hub $1, https +
+# release API only (a provider yaml carries endpoints the server will call —
+# no plain-git / local / http source). Validation, planning and the write into
+# ~/.halo/global/models.d/ belong to `halo models install` ($HALO_CLI in dev);
+# its exit code (3 = endpoint changes need --yes) passes through.
+models_update() {
+  local hub=$1 platform zip; shift
+  if [[ $hub != https://* ]]; then
+    echo "model configs need an https release hub (GitHub / Gitea / Forgejo / GitLab) — $hub is not one" >&2; exit 1
+  fi
+  platform=$(hub_platform "$hub")
+  if [[ $platform == git ]]; then
+    echo "model configs need a release-API hub (GitHub / Gitea / Forgejo / GitLab) — $hub has no release API" >&2; exit 1
+  fi
+  zip=$(hub_fetch_release "$platform" "$hub" models "$TMP" --proto =https --proto-redir =https)
+  safe_unzip "$zip" "$TMP/models"
+  local dir="$TMP/models" only
+  # A zip wrapping everything in one directory — descend into it.
+  if ! compgen -G "$dir/*.yaml" >/dev/null; then
+    only=$(find "$dir" -mindepth 1 -maxdepth 1 | head -2)
+    if [[ $(printf '%s\n' "$only" | wc -l) -eq 1 && -d $only ]]; then dir=$only; fi
+  fi
+  # Last command: under `set -e` its non-zero status (3 = confirm) is the script's.
+  "${HALO_CLI:-halo}" models install "$dir" "$@"
+}
+
 # Echo a local zip or an unpacked package dir for source $1 (path, https URL, or hub id).
 resolve_source() {
   local src=$1
@@ -196,12 +243,7 @@ case $cmd in
     if [[ -d $pkg ]]; then
       dir=$pkg
     else
-      # Same refusals as the server's zip installer: no `..`, no absolute paths,
-      # no symlinks (zipinfo mode column starts with `l`).
-      if unzip -Z1 "$pkg" | grep -Eq '(^|/)\.\.(/|$)|^/'; then echo "zip contains ../ or absolute entries" >&2; exit 1; fi
-      if unzip -Z "$pkg" | grep -q '^l'; then echo "zip contains symlinks" >&2; exit 1; fi
-      mkdir -p "$TMP/x"
-      unzip -q "$pkg" -d "$TMP/x"
+      safe_unzip "$pkg" "$TMP/x"
       # `zip -r glb.zip glb/` wraps everything in one directory — descend into it.
       dir="$TMP/x"
       if [[ ! -f $dir/halo-extension.json ]]; then
@@ -239,6 +281,17 @@ case $cmd in
     [[ -d $ROOT/$id ]] || { echo "not installed: $id" >&2; exit 1; }
     rm -rf "$ROOT/$id"
     echo "removed $id" ;;
+  models)
+    sub=${1:-update}
+    shift || true
+    case $sub in
+      list) exec "${HALO_CLI:-halo}" models list ;;
+      update)
+        for a in "$@"; do [[ $a == --yes ]] || { echo "usage: ext.sh models update [--yes] | models list" >&2; exit 1; }; done
+        TMP=$(mktemp -d); trap 'rm -rf "$TMP"' EXIT
+        models_update "$(hub_url "${HALO_HUB_REPO:-}")" "$@" ;;
+      *) echo "usage: ext.sh models update [--yes] | models list" >&2; exit 1 ;;
+    esac ;;
   *)
-    echo "unknown command: $cmd (install | list | remove)" >&2; exit 1 ;;
+    echo "unknown command: $cmd (install | list | remove | models)" >&2; exit 1 ;;
 esac

package/templates/skills/self/SKILL.md

@@ -63,9 +63,10 @@ not per-conversation.)
   not a fallback. Anything untranslated is stripped.
 - `self.play(score)` — choreograph a sequence; the face keeps the clock so you
   never hand-write `setTimeout` chains. `score` is an array of beats, each one
-  of: `{say, hold, pulse, flash, shake, rest, gap}`. Calling it again cancels the
+  of: `{say, show, hold, pulse, flash, shake, rest, gap}`. Calling it again cancels the
   running score. Example — a short greeting:
   `self.play([{say:"HI",hold:1800},{say:"...",hold:1200},{say:"OK",hold:1500},{pulse:true}])`
+  A `show` beat puts an image on the face (see `self.show`): `{show:"<path>", hold:3000}`.
 - `self.react(event)` — a named vocabulary of honest reactions for the small
   beats of a conversation, so you can answer a moment in one word:
   `'ack'` (a nod), `'yes'`, `'no'` (disagree / that's wrong), `'insight'` (a real
@@ -89,10 +90,28 @@ not per-conversation.)
   one.) It starts immediately (not queued) and owns the matrix until the clip
   ends, then eases home. Drive it the moment the audio is ready, in the same
   reply that delivers the spoken answer.
+- `self.show(path, ms)` — put an image on the face. The dots fly in and gather
+  into the picture's outline (~1 s), then the real image fades in over them —
+  dots alone can't carry a chart's text, so the real image is always there — holds
+  for `ms` (default 6000), fades out, and the dots dissolve back to breathing.
+  The image fits ~80% of the window, aspect preserved, centered. Like `voice`,
+  pass the **workspace path** (`self.show(".halo/tmp/chart.png", 5000)`); the face
+  resolves the URL itself, no projectId. `ms = Infinity` keeps it up until the
+  next scene, `self.rest()`, or a click on the page. Formats: png / jpg / jpeg /
+  webp / gif / svg only. A missing or non-image file doesn't stall anything — it
+  warns, shakes, and the next beat plays. `.excalidraw` / `.drawio` are editor
+  sources and can't be shown: **for a diagram, write an SVG file directly and show
+  it.** It queues like `say()`, so several `show()`s and `say()`s play in order,
+  and a `voice()` clip keeps rippling the field around the picture. A talking
+  picture book (word audio + picture + the word on the dots):
+  `self.voice(".halo/tmp/apple.mp3")` then
+  `self.play([{show:".halo/tmp/apple.png",hold:3000},{say:"APPLE",hold:1500}])`.
 - `self.rest()` — return to the calm breathing state immediately (also stops a
-  playing voice clip, so the face never breathes calmly over still-sounding audio).
-- `self.state` — read current `{mode, awake, W, H, speaking, level}` if you need
-  it (`speaking` = a voice clip is playing, `level` = its live loudness 0..1).
+  playing voice clip and removes a shown image, so the face never breathes calmly
+  over still-sounding audio).
+- `self.state` — read current `{mode, awake, W, H, speaking, level, showing}` if
+  you need it (`speaking` = a voice clip is playing, `level` = its live loudness
+  0..1, `showing` = an image is on the face).
 
 You can also send *any* JavaScript — `self` is the surface, but the code runs in
 the page, so improvisation beyond these helpers is allowed (it's sandboxed to the