pinokiod 7.0.6 → 7.0.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pinokiod",
-  "version": "7.0.6",
+  "version": "7.0.9",
   "description": "",
   "main": "index.js",
   "scripts": {

package/prototype/system/SKILL_PINOKIO.md

@@ -40,7 +40,7 @@ Failure handling:
 
 Use direct `pterm` commands for control-plane operations:
 
-`pterm search`, `pterm status`, `pterm run`, `pterm logs`, `pterm upload`, `pterm which`, `pterm stars`, `pterm star` / `pterm unstar`, `pterm registry search`, `pterm download`
+`pterm search`, `pterm status`, `pterm run`, `pterm open`, `pterm logs`, `pterm upload`, `pterm which`, `pterm stars`, `pterm star` / `pterm unstar`, `pterm registry search`, `pterm download`
 
 Do not run update commands from this skill.
 Once a Pinokio-managed app is selected, treat `pterm` and the launcher-managed interfaces as the source of truth for lifecycle and execution. Do not switch to repo-local CLIs or bundled app binaries unless the user explicitly asks for CLI mode.
@@ -50,8 +50,8 @@ Once a Pinokio-managed app is selected, treat `pterm` and the launcher-managed i
 Follow these sections in order:
 1. Use Search App first.
 2. Only use Registry Fallback if Search App found no suitable installed app and the user approved it.
-3. Then use Run App.
-4. Then use API Call Strategy if the app exposes an automatable API.
+3. Then use Launch App.
+4. Then use Using Apps if the app exposes an automatable API.
 5. Only use Parallel Mode when the user explicitly asks to use multiple apps or multiple machines in parallel.
 
 ### 1. Search App
@@ -88,7 +88,7 @@ Follow these sections in order:
     - more recent `last_launch_at` (if available)
     - higher `score`
 - If the top candidate is not clearly better than alternatives, ask user once with top 3 candidates.
-- If a suitable installed app is found, select it and continue to Run App.
+- If a suitable installed app is found, select it and continue to Launch App.
 - Search results may include apps from other reachable Pinokio machines:
   - prefer the canonical `ref` field when it exists
   - `ref` uses the form `pinokio://<host>:<port>/<scope>/<id>`
@@ -108,7 +108,7 @@ Follow these sections in order:
   - then run the downloaded app with `pterm run <local_app_path_or_name>`
 - Do not use `pterm run <url>` for the registry flow.
 
-### 3. Run App
+### 3. Launch App
 
 - Once you have a selected app, use `pterm status`.
 - Poll every 2s.
@@ -145,6 +145,17 @@ Follow these sections in order:
   - use `ready_url` by default when it exists and is caller-usable
   - if `ready_url` is missing, or it fails because the client cannot access loopback, and `external_ready_urls` exists, try those URLs in order
   - missing `external_ready_urls` is normal; it usually means network sharing is off
+- If the user explicitly wants to open the app UI or open a web page in a browser or popup window:
+  - use `pterm open <url>`
+  - only do this for explicit viewing/manual interaction requests, not for normal API automation
+  - use a caller-usable app URL:
+    - `ready_url` when it exists and the current machine can reach it
+    - otherwise the first usable entry from `external_ready_urls`
+  - default behavior should be popup-preferred:
+    - on a desktop Pinokio node, it opens a Pinokio popup window
+    - on a server-only or minimal node, it falls back to the system browser automatically
+  - use `--surface browser` only when the user explicitly wants the system browser instead of the default popup-preferred behavior
+  - if popup sizing matters and the user does not specify one, default to `--preset center-medium`
 - Failure criteria:
   - timeout before success
   - app drops back to `offline` during startup after a run attempt
@@ -152,27 +163,89 @@ Follow these sections in order:
   - on failure, fetch `pterm logs <ref> --tail 200` when `ref` exists, otherwise `pterm logs <app_id> --tail 200`, and return:
     - raw log tail
     - short diagnosis
+- After successful task completion:
+  - do not stop or shut down the app unless the user explicitly asks
+  - prefer leaving a successfully running app online for reuse
 
-### 4. API Call Strategy (generated once, reused)
-- Resolve path roots before writing agent-owned files:
-  - prefer the current working directory when it is the active writable task/workspace folder
-  - resolve `PINOKIO_HOME` with `pterm home` when fallback global storage is needed
-- Generated client location:
-  - local default: `<current_working_directory>/pinokio_agent/clients/<app_id>/<operation>.<ext>`
-  - fallback: `<PINOKIO_HOME>/agents/clients/<app_id>/<operation>.<ext>`
-- Output location:
-  - local default: `<current_working_directory>/pinokio_agent/output/<app_id>/...`
-  - fallback: `<PINOKIO_HOME>/agents/output/<app_id>/...`
-- First run for `<app_id>/<operation>`:
+### 4. Using Apps
+- Create or reuse one app-specific skill folder for the selected app:
+  - local default: `<current_working_directory>/pinokio_agent/skills/<scope>/<app_id>/`
+  - fallback: `<PINOKIO_HOME>/agents/skills/<scope>/<app_id>/`
+- App-specific skill folder structure:
+  - `SKILL.md`: short instructions for how to use this app
+    - include frontmatter with only:
+      - `name`: short stable app-specific skill name using lowercase letters, digits, and hyphens only; derive it from a normalized app identity such as `<scope>-<app_id>` and keep it under 64 characters
+      - `description`: one clear sentence describing what this app-specific skill does and when it should be used
+  - optional `clients/`: reusable local client files
+  - optional `references/`: saved API artifacts such as OpenAPI specs, Gradio config, or concise notes
+  - outputs: `<app_skill_folder>/output/<target_host>/...`
+
+- Reuse an existing app-specific skill when possible:
+  - if `<app_skill_folder>/SKILL.md` exists and still describes the app's current API correctly, read it first and follow it
+  - if the folder already contains a reusable client for the needed operation and it still works against the current app API, reuse that client
+  - if the folder has no `SKILL.md`, or the saved instructions or saved client no longer match the current API, rediscover the app interface and rewrite the app-specific skill folder
+
+- If rediscovery is needed, choose exactly one usage mode:
+  - Mode A: use the app directly
+  - Mode B: reuse or generate a reusable client
+- Use Mode A only if all of these are true:
+  - the running app already exposes a documented HTTP API you can call directly
+  - the task is simple enough to complete with one or a few direct requests
+  - saving a client file would not make later work meaningfully easier
+- Standard callable API examples:
+  - OpenAPI / Swagger endpoints
+  - FastAPI docs
+  - Gradio API
+  - other documented standard HTTP interfaces
+- Otherwise use Mode B.
+
+- Shared rules for both modes:
+  - prefer documented/public APIs exposed by the running launcher
+  - choose a base URL that the current machine can actually reach:
+    - use `ready_url` when it exists and the current machine can reach it
+    - otherwise use `external_ready_urls` in order
+  - if the task needs remote filesystem paths, first run `pterm upload <ref> <file...>` and use the returned remote paths for that target only
+  - never reuse a remote uploaded path from one target on another target
+  - keep `<app_skill_folder>/SKILL.md` concise and operational
+  - put bulky raw artifacts in `references/` instead of bloating `SKILL.md`
+
+- Mode A: use the app directly
+  - execute the needed requests directly from the current machine
+  - update `<app_skill_folder>/SKILL.md` to record:
+    - what callable API surface exists
+    - how to choose the base URL
+    - required request inputs and outputs
+    - whether remote upload is needed for path-based tasks
+  - do not create a reusable client in this mode unless the workflow later becomes repetitive or multi-step enough to justify Mode B
+
+- Mode B: reuse or generate a reusable client
+  - if no matching client exists under `<app_skill_folder>/clients/` for the needed operation, generate one
+  - if a client exists but the contract no longer matches, regenerate it only for:
+    - 404/405 endpoint mismatch
+    - 400/422 payload/schema mismatch
+    - auth/header mismatch
   - inspect docs/code to infer endpoint + payload
-  - generate minimal HTTP client file (`js`/`py`/`sh`)
-- Later runs:
-  - reuse existing generated client file directly
-- Regenerate only if request indicates contract mismatch:
-  - 404/405 endpoint mismatch
-  - 400/422 payload/schema mismatch
-  - auth/header mismatch
-- Prefer documented/public app APIs exposed by the running launcher.
+  - generate a minimal cross-platform HTTP client in `py` or `js`
+  - do not use Bash, PowerShell, or other machine-specific shell scripts for reusable clients unless the user explicitly asks for a machine-local one-off script
+  - generated clients run on the current machine; do not copy or write them onto the remote machine
+  - organize clients by app and operation, not by host
+    - example: if local Cropper and remote Cropper use the same endpoint and payload shape for `trim`, reuse one client such as `clients/trim.py`
+  - do not create a second client file only because the target host changed
+  - pass per-run values into the client at execution time:
+    - a base URL that the current machine can actually reach
+    - uploaded remote file paths when needed
+    - per-run auth headers/cookies if required
+  - never hardcode per-run values into the saved client:
+    - `ref`
+    - base URL / host / port
+    - uploaded temp file paths
+    - per-run auth tokens or cookies
+  - update `<app_skill_folder>/SKILL.md` to record:
+    - which client file to use for each operation
+    - required runtime arguments
+    - expected outputs
+    - when the client should be regenerated
+
 - Do not execute the app's internal Python/Node/bundled CLI as a fallback when `pterm` has already selected a launcher-managed app.
 - If no automatable API exists after the app is running, report that clearly instead of bypassing the launcher with an internal CLI.
 
@@ -193,9 +266,15 @@ Follow these sections in order:
   - prefer `ready` apps first
   - then `running` apps
   - then offline apps if more targets are still needed
+- If subagents are available, prefer one subagent per selected target.
+  - the main agent should do the search, choose the targets, and aggregate the final results
+  - each subagent should own exactly one target `ref` when it exists, otherwise one `app_id`
+  - each subagent should run status/run/logs/upload only for its own target
 - Run and monitor each selected target independently.
 - Keep outputs labeled by target `ref` when it exists, otherwise `app_id`.
 - For remote path-based tasks, run `pterm upload <ref> <file...>` separately for each remote target when `ref` exists, otherwise fall back to `app_id`.
+- Do not reuse one target's uploaded remote file path for another target.
+- If subagents are unavailable, keep the same per-target separation and run the targets sequentially.
 
 ## Behavior Rules
 
@@ -204,8 +283,8 @@ Follow these sections in order:
 - Do not rewrite launcher files unless user explicitly asked.
 - When a task needs a local executable such as `python`, prefer resolving it with `pterm which <command>` before falling back to generic shell discovery.
 - Prefer returning full logs over brittle deterministic error parsing.
-- REST endpoints may be used for diagnostics only when pterm is unavailable; do not claim full install/launch lifecycle completion without compatible pterm commands.
-- Do not keep searching after app selection; move to status/run.
+- Pinokio control-plane REST endpoints may be used for diagnostics only when `pterm` is unavailable; do not claim full install/launch lifecycle completion without compatible `pterm` commands.
+- Do not keep searching after app selection; move to Launch App.
 - Do not assume `external_ready_urls` exists; localhost-only apps are normal.
 - Do not conflate loopback access failure, sandbox denial, or missing permission with "Pinokio is not running" or "`pterm` is not installed."
 - On `pterm` permission failure, prefer asking for permission over asking the user to manually run commands.
@@ -215,8 +294,14 @@ Follow these sections in order:
 
 User: "Launch FaceFusion"
 
-1. Use Search App and then Run App as usual.
+1. Use Search App and then Launch App as usual.
 2. If launcher menu has no explicit default item, infer ordered selectors from the current launcher menu.
 3. Run:
-   `pterm run <app_path> --default 'run.js?mode=Default' --default run.js --default install.js`
-4. Poll `pterm status <app_id>` until ready.
+   - if `ref` exists:
+     `pterm run <ref> --default 'run.js?mode=Default' --default run.js --default install.js`
+   - otherwise:
+     `pterm run <app_path> --default 'run.js?mode=Default' --default run.js --default install.js`
+4. Poll:
+   - `pterm status <ref>` when `ref` exists
+   - otherwise `pterm status <app_id>`
+   until ready.

package/server/index.js

@@ -46,6 +46,7 @@ const NOTIFICATION_SOUND_EXTENSIONS = new Set(['.aac', '.flac', '.m4a', '.mp3',
 const LOG_STREAM_INITIAL_BYTES = 512 * 1024
 const LOG_STREAM_KEEPALIVE_MS = 25000
 const DEFAULT_REGISTRY_URL = 'https://beta.pinokio.co'
+const LOOPBACK_HOSTS = new Set(['127.0.0.1', 'localhost', '::1', '[::1]'])
 
 const ex = fn => (req, res, next) => {
   Promise.resolve(fn(req, res, next)).catch(next);
@@ -8592,6 +8593,191 @@ class Server {
       Util.openURL(req.body.url)
       res.json({ success: true })
     }))
+    this.app.post("/pinokio/open", ex(async (req, res) => {
+      const url = typeof req.body.url === 'string' ? req.body.url.trim() : ''
+      if (!url) {
+        res.status(400).json({ error: 'Missing url' })
+        return
+      }
+      const normalizeSurface = (value) => {
+        return String(value || '').trim().toLowerCase() === 'browser' ? 'browser' : 'popup'
+      }
+      const normalizePreset = (value) => {
+        const normalized = String(value || '').trim().toLowerCase()
+        if (normalized === 'center-small' || normalized === 'center-medium' || normalized === 'center-large' || normalized === 'fullscreen') {
+          return normalized
+        }
+        return 'center-medium'
+      }
+      const defaultPeerPort = () => {
+        const rawPort = Number.parseInt(String(this.kernel?.peer?.default_port || this.kernel?.server_port || this.port || DEFAULT_PORT), 10)
+        return Number.isFinite(rawPort) && rawPort > 0 ? rawPort : DEFAULT_PORT
+      }
+      const currentPeerHost = () => {
+        return this.kernel && this.kernel.peer && this.kernel.peer.host
+          ? String(this.kernel.peer.host).trim()
+          : ''
+      }
+      const currentPeerName = () => {
+        return this.kernel && this.kernel.peer && this.kernel.peer.name
+          ? String(this.kernel.peer.name).trim()
+          : ''
+      }
+      const isLocalPeerToken = (value) => {
+        const normalized = String(value || '').trim().toLowerCase()
+        return !!normalized && (LOOPBACK_HOSTS.has(normalized) || normalized === currentPeerHost().toLowerCase() || normalized === currentPeerName().toLowerCase())
+      }
+      const resolvePeerTarget = (rawValue) => {
+        const localHost = currentPeerHost() || '127.0.0.1'
+        const localName = currentPeerName() || localHost
+        const fallbackPort = defaultPeerPort()
+        if (rawValue === undefined || rawValue === null || String(rawValue).trim() === '') {
+          return {
+            local: true,
+            host: localHost,
+            port: fallbackPort,
+            name: localName
+          }
+        }
+        const trimmed = String(rawValue).trim()
+        let hostOrName = trimmed
+        let port = fallbackPort
+        const separatorIndex = trimmed.lastIndexOf(':')
+        if (separatorIndex > 0 && separatorIndex < trimmed.length - 1) {
+          const possiblePort = trimmed.slice(separatorIndex + 1).trim()
+          if (/^\d+$/.test(possiblePort)) {
+            hostOrName = trimmed.slice(0, separatorIndex).trim()
+            const explicitPort = Number.parseInt(possiblePort, 10)
+            if (Number.isFinite(explicitPort) && explicitPort > 0) {
+              port = explicitPort
+            }
+          }
+        }
+        if (!hostOrName) {
+          return {
+            error: 'Invalid peer'
+          }
+        }
+        if (isLocalPeerToken(hostOrName)) {
+          return {
+            local: true,
+            host: localHost,
+            port,
+            name: localName
+          }
+        }
+        if (this.kernel && this.kernel.peer && this.kernel.peer.info && typeof this.kernel.peer.info === 'object') {
+          for (const [host, info] of Object.entries(this.kernel.peer.info)) {
+            const peerName = info && info.name ? String(info.name).trim() : ''
+            if (host === hostOrName || (peerName && peerName === hostOrName)) {
+              return {
+                local: host === localHost,
+                host,
+                port,
+                name: peerName || host
+              }
+            }
+          }
+        }
+        if (LOOPBACK_HOSTS.has(hostOrName.toLowerCase())) {
+          return {
+            local: true,
+            host: localHost,
+            port,
+            name: localName
+          }
+        }
+        if (/^(?:\d{1,3}\.){3}\d{1,3}$/.test(hostOrName)) {
+          return {
+            local: false,
+            host: hostOrName,
+            port,
+            name: hostOrName
+          }
+        }
+        return {
+          error: `Unknown peer: ${trimmed}`
+        }
+      }
+      const requestedSurface = normalizeSurface(req.body.surface)
+      const requestedPreset = normalizePreset(req.body.preset)
+      const peerTarget = resolvePeerTarget(req.body.peer)
+      if (peerTarget.error) {
+        res.status(400).json({ error: peerTarget.error })
+        return
+      }
+      if (!peerTarget.local) {
+        try {
+          const response = await axios.post(`http://${peerTarget.host}:${peerTarget.port}/pinokio/open`, {
+            url,
+            surface: requestedSurface,
+            preset: requestedPreset
+          }, {
+            timeout: 5000,
+            headers: {
+              'x-pinokio-peer': '1'
+            }
+          })
+          res.json({
+            ...(response.data && typeof response.data === 'object' ? response.data : { success: true }),
+            peer: {
+              host: peerTarget.host,
+              port: peerTarget.port,
+              name: peerTarget.name || peerTarget.host,
+              local: false
+            }
+          })
+          return
+        } catch (error) {
+          const remoteMessage = error && error.response && error.response.data && error.response.data.error
+            ? error.response.data.error
+            : (error && error.message ? error.message : 'Peer open failed')
+          res.status(502).json({
+            error: remoteMessage,
+            peer: {
+              host: peerTarget.host,
+              port: peerTarget.port,
+              name: peerTarget.name || peerTarget.host,
+              local: false
+            }
+          })
+          return
+        }
+      }
+      let result
+      if (this.browser && typeof this.browser.open === 'function') {
+        result = await Promise.resolve(this.browser.open({
+          url,
+          surface: requestedSurface,
+          preset: requestedPreset
+        }))
+      }
+      if (!result || result.ok === false) {
+        Util.openURL(url)
+        result = {
+          ok: true,
+          surface_used: 'browser'
+        }
+      }
+      const surfaceUsed = typeof result.surface_used === 'string' && result.surface_used
+        ? result.surface_used
+        : 'browser'
+      res.json({
+        success: true,
+        url,
+        requested_surface: requestedSurface,
+        surface_used: surfaceUsed,
+        preset_used: surfaceUsed === 'popup'
+          ? (typeof result.preset_used === 'string' && result.preset_used ? result.preset_used : requestedPreset)
+          : null,
+        peer: {
+          host: peerTarget.host,
+          port: peerTarget.port,
+          name: peerTarget.name || peerTarget.host,
+          local: true
+        }
+      })
+    }))
     this.app.post("/openfs", ex(async (req, res) => {
       //Util.openfs(req.body.path, req.body.mode)
       if (req.body.name) {