pinokiod 7.0.5 → 7.0.8

package/package.json

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

package/prototype/system/SKILL_PINOKIO.md

@@ -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,9 +88,10 @@ 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:
-  - remote results use `app_id` in the form `<app_id>@<source.host>`
+  - prefer the canonical `ref` field when it exists
+  - `ref` uses the form `pinokio://<host>:<port>/<scope>/<id>`
   - `source.local=false` means the result is from another machine
   - treat remote results as separate apps; do not merge them with the local app of the same name
 
@@ -107,12 +108,13 @@ 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.
 - Use status fields from pterm output:
   - `path`: absolute app path to use with `pterm run`
+  - `ref`: canonical Pinokio resource reference in the form `pinokio://<host>:<port>/<scope>/<id>`
   - `running`: script is running
   - `ready`: app is reachable/ready
   - `ready_url`: default base URL for API calls when available
@@ -122,21 +124,21 @@ Follow these sections in order:
 - Use `--probe` only for readiness confirmation before first API call (or when status is uncertain).
 - Use `--timeout=<ms>` only when you need a non-default probe timeout.
 - Treat `offline` as expected before first run.
-- If `app_id` contains `@<host>` or `source.local=false`, the app is remote:
+- If `ref` points to another machine or `source.local=false`, the app is remote:
   - treat `path` and `ready_url` as source-local fields, not caller-usable local paths/URLs
   - use `external_ready_urls` in order for caller-side API access when available
-  - use `pterm run <app_id>` for remote launch; do not use a remote machine's `path` value as a local path
+  - use `pterm run <ref>` for remote launch; do not use a remote machine's `path` value as a local path
   - for remote path-based tasks:
     - this applies only when the task expects filesystem paths such as `/path/to/file`
     - do not pass local paths from this machine to the remote app
-    - first run `pterm upload <app_id> <file...>`
+    - first run `pterm upload <ref> <file...>`
     - then use the returned remote `path` values
 - If app is offline or not ready, run it:
-  - For remote apps, run `pterm run <app_id>`.
+  - If `ref` exists, run `pterm run <ref>`.
   - Otherwise run `pterm run <app_path>`.
   - If the launcher has no explicit default item or the launch action depends on current menu state, infer one or more ordered selectors from the launcher's current menu and pass them via repeated `--default`.
   - Prefer stable launcher selectors such as `run.js?mode=Default`, then broader fallbacks like `run.js`, then installation fallback like `install.js`.
-  - Continue polling with `pterm status <app_id>`.
+  - Continue polling with `pterm status <ref>` when `ref` exists, otherwise `pterm status <app_id>`.
   - Default startup timeout: 180s.
 - Success criteria:
   - `state=online` and `ready=true`
@@ -147,30 +149,92 @@ Follow these sections in order:
   - timeout before success
   - app drops back to `offline` during startup after a run attempt
   - `pterm run` terminates and status never reaches ready
-  - on failure, fetch `pterm logs <app_id> --tail 200` and return:
+  - 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.
 
@@ -182,7 +246,7 @@ Follow these sections in order:
   - compare multiple relevant apps side by side
   - generate multiple outputs concurrently
 - Do not use this mode by default.
-- Keep each selected app as a separate target, including remote results like `<app_id>@<source.host>`.
+- Keep each selected app as a separate target. Prefer `ref` as the target identifier when it exists.
 - Selection rules:
   - if the user asks for all relevant apps, use all relevant search results that can perform the task
   - if the user asks for a specific count, use the top N relevant search results after normal search ranking
@@ -191,9 +255,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 `app_id`.
-- For remote path-based tasks, run `pterm upload <app_id> <file...>` separately for each remote target and use that target's returned remote `path` values.
+- 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
 
@@ -202,8 +272,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.
@@ -213,8 +283,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() === 'popup' ? 'popup' : 'browser'
+      }
+      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) {

package/server/routes/apps.js

@@ -11,6 +11,7 @@ const DEFAULT_PEER_PORT = 42000
 const DEFAULT_PEER_TIMEOUT_MS = 2500
 const DEFAULT_PEER_UPLOAD_TIMEOUT_MS = 30000
 const IPV4_HOST_PATTERN = /^(?:\d{1,3}\.){3}\d{1,3}$/
+const PINOKIO_REF_PROTOCOL = 'pinokio:'
 
 const isQualifiedHost = (value = '') => {
   return IPV4_HOST_PATTERN.test(String(value || '').trim())
@@ -56,6 +57,84 @@ const parseQualifiedAppId = (value = '') => {
   }
 }
 
+const isLoopbackHost = (value = '') => {
+  const normalized = String(value || '').trim().toLowerCase()
+  return normalized === '127.0.0.1' || normalized === 'localhost' || normalized === '::1' || normalized === '[::1]'
+}
+
+const parsePinokioRef = (value = '') => {
+  if (typeof value !== 'string') {
+    return {
+      valid: false,
+      error: 'Invalid ref'
+    }
+  }
+  const trimmed = value.trim()
+  if (!trimmed) {
+    return {
+      valid: false,
+      error: 'Missing ref'
+    }
+  }
+  let parsed
+  try {
+    parsed = new URL(trimmed)
+  } catch (_) {
+    return {
+      valid: false,
+      error: 'Invalid ref'
+    }
+  }
+  if (parsed.protocol !== PINOKIO_REF_PROTOCOL) {
+    return {
+      valid: false,
+      error: 'Invalid ref protocol'
+    }
+  }
+  const host = typeof parsed.hostname === 'string' ? parsed.hostname.trim() : ''
+  const port = Number.parseInt(String(parsed.port || ''), 10)
+  const pathSegments = String(parsed.pathname || '')
+    .split('/')
+    .filter(Boolean)
+    .map((segment) => {
+      try {
+        return decodeURIComponent(segment)
+      } catch (_) {
+        return segment
+      }
+    })
+  const scope = pathSegments.length > 0 ? pathSegments[0] : ''
+  const id = pathSegments.length > 1 ? pathSegments.slice(1).join('/') : ''
+  if (!host || !Number.isFinite(port) || port <= 0 || !scope || !id) {
+    return {
+      valid: false,
+      error: 'Invalid ref'
+    }
+  }
+  return {
+    valid: true,
+    ref: trimmed,
+    host,
+    port,
+    scope,
+    id
+  }
+}
+
+const buildPinokioRef = ({ host, port, scope, id }) => {
+  const normalizedHost = typeof host === 'string' ? host.trim() : ''
+  const normalizedScope = typeof scope === 'string' ? scope.trim() : ''
+  const normalizedId = typeof id === 'string' ? id.trim() : ''
+  const normalizedPort = Number.parseInt(String(port || ''), 10)
+  if (!normalizedHost || !normalizedScope || !normalizedId || !Number.isFinite(normalizedPort) || normalizedPort <= 0) {
+    return null
+  }
+  const encodedPath = [normalizedScope, ...normalizedId.split('/').filter(Boolean)]
+    .map((segment) => encodeURIComponent(segment))
+    .join('/')
+  return `pinokio://${normalizedHost}:${normalizedPort}/${encodedPath}`
+}
+
 module.exports = function registerAppRoutes(app, { registry, preferences, appSearch, appLogs, getTheme }) {
   if (!app || !registry || !preferences || !appSearch || !appLogs) {
     throw new Error('App routes require app, registry, preferences, appSearch, and appLogs')
@@ -120,6 +199,43 @@ module.exports = function registerAppRoutes(app, { registry, preferences, appSea
     }
     return `${normalizedAppId}@${host}`
   }
+  const canonicalRefHost = (source, overrideHost = '') => {
+    const hostOverride = typeof overrideHost === 'string' ? overrideHost.trim() : ''
+    if (hostOverride) {
+      return hostOverride
+    }
+    if (source && typeof source.host === 'string' && source.host.trim()) {
+      return source.host.trim()
+    }
+    return currentPeerHost() || '127.0.0.1'
+  }
+  const isLocalPinokioRef = (parsedRef) => {
+    if (!parsedRef || !parsedRef.valid) {
+      return false
+    }
+    if (parsedRef.port !== peerPort()) {
+      return false
+    }
+    const localHost = currentPeerHost()
+    return isLoopbackHost(parsedRef.host) || (localHost && parsedRef.host === localHost)
+  }
+  const attachApiRef = (payload, source, appId, options = {}) => {
+    const next = payload && typeof payload === 'object' ? { ...payload } : {}
+    const normalizedAppId = typeof appId === 'string' ? appId.trim() : ''
+    if (!normalizedAppId) {
+      return next
+    }
+    const ref = buildPinokioRef({
+      host: canonicalRefHost(source, options.host),
+      port: Number.parseInt(String(options.port || peerPort()), 10) || peerPort(),
+      scope: 'api',
+      id: normalizedAppId
+    })
+    if (ref) {
+      next.ref = ref
+    }
+    return next
+  }
   const neutralizeRemoteSearchPreferences = (appResult) => {
     const next = appResult && typeof appResult === 'object' ? { ...appResult } : {}
     next.starred = false
@@ -153,25 +269,31 @@ module.exports = function registerAppRoutes(app, { registry, preferences, appSea
     const parsed = Date.parse(value)
     return Number.isFinite(parsed) ? parsed : 0
   }
-  const decorateSearchResult = (appResult, source) => {
+  const decorateSearchResult = (appResult, source, options = {}) => {
     const next = source && !source.local
       ? neutralizeRemoteSearchPreferences(appResult)
       : (appResult && typeof appResult === 'object' ? { ...appResult } : {})
-    next.app_id = qualifyAppId(next.app_id || next.name || '', source.host)
+    const resourceId = typeof next.app_id === 'string' && next.app_id.trim()
+      ? next.app_id.trim()
+      : (typeof next.name === 'string' ? next.name.trim() : '')
+    next.app_id = qualifyAppId(resourceId, source.host)
     next.source = source
     if (!source.local) {
       next.ready_url = null
     }
-    return next
+    return attachApiRef(next, source, resourceId, options)
   }
-  const decorateStatusResult = (statusResult, source) => {
+  const decorateStatusResult = (statusResult, source, options = {}) => {
     const next = statusResult && typeof statusResult === 'object' ? { ...statusResult } : {}
-    next.app_id = qualifyAppId(next.app_id || next.name || '', source.host)
+    const resourceId = typeof next.app_id === 'string' && next.app_id.trim()
+      ? next.app_id.trim()
+      : (typeof next.name === 'string' ? next.name.trim() : '')
+    next.app_id = qualifyAppId(resourceId, source.host)
     next.source = source
     if (!source.local) {
       next.ready_url = null
     }
-    return next
+    return attachApiRef(next, source, resourceId, options)
   }
   const peerRequestHeaders = (req) => {
     const headers = {
@@ -245,11 +367,11 @@ module.exports = function registerAppRoutes(app, { registry, preferences, appSea
       files: stored
     }
   }
-  const decorateUploadResult = (uploadResult, source, appId) => {
+  const decorateUploadResult = (uploadResult, source, appId, options = {}) => {
     const next = uploadResult && typeof uploadResult === 'object' ? { ...uploadResult } : {}
     next.app_id = qualifyAppId(appId || next.app_id || '', source.host)
     next.source = source
-    return next
+    return attachApiRef(next, source, appId || next.app_id || '', options)
   }
   const mergeSearchApps = (localApps, remoteApps, query = '') => {
     const merged = []
@@ -400,6 +522,255 @@ module.exports = function registerAppRoutes(app, { registry, preferences, appSea
     res.json({ apps })
   }))
 
+  router.get('/pinokio/resource/status', asyncHandler(async (req, res) => {
+    const parsedRef = parsePinokioRef(typeof req.query.ref === 'string' ? req.query.ref : '')
+    if (!parsedRef.valid) {
+      res.status(400).json({ error: parsedRef.error || 'Invalid ref' })
+      return
+    }
+    if (parsedRef.scope !== 'api') {
+      res.status(400).json({ error: `Unsupported ref scope: ${parsedRef.scope}` })
+      return
+    }
+    const canonicalRef = buildPinokioRef(parsedRef)
+    if (!isLocalPinokioRef(parsedRef)) {
+      try {
+        const timeout = Number.parseInt(String(req.query.timeout || ''), 10)
+        const params = { ref: canonicalRef }
+        if (typeof req.query.probe !== 'undefined') {
+          params.probe = req.query.probe
+        }
+        if (Number.isFinite(timeout)) {
+          params.timeout = String(timeout)
+        }
+        const response = await axios.get(`http://${parsedRef.host}:${parsedRef.port}/pinokio/resource/status`, {
+          timeout: DEFAULT_PEER_TIMEOUT_MS,
+          headers: peerRequestHeaders(req),
+          params
+        })
+        const payload = decorateStatusResult(response.data, buildSource(parsedRef.host, false), {
+          host: parsedRef.host,
+          port: parsedRef.port
+        })
+        payload.app_id = parsedRef.id
+        payload.ref = canonicalRef
+        res.json(payload)
+        return
+      } catch (error) {
+        if (error && error.response) {
+          res.status(error.response.status).json(error.response.data)
+          return
+        }
+        res.status(502).json({
+          error: 'Peer resource status unavailable',
+          ref: canonicalRef,
+          source: buildSource(parsedRef.host, false)
+        })
+        return
+      }
+    }
+    const appId = registry.normalizeAppId(parsedRef.id)
+    if (!appId) {
+      res.status(400).json({ error: 'Invalid app_id', ref: canonicalRef })
+      return
+    }
+    const probe = registry.parseBooleanQuery(req.query.probe, false)
+    const timeout = Number.parseInt(String(req.query.timeout || ''), 10)
+    const status = await registry.buildAppStatus(appId, {
+      probe,
+      timeout: Number.isFinite(timeout) ? timeout : 1500,
+      source: req.$source || null
+    })
+    if (!status) {
+      res.status(404).json({ error: 'App not found', ref: canonicalRef })
+      return
+    }
+    status.preference = await preferences.getPreference(appId)
+    const payload = decorateStatusResult(status, buildSource(currentPeerHost(), true), {
+      host: parsedRef.host,
+      port: parsedRef.port
+    })
+    payload.app_id = appId
+    payload.ref = canonicalRef
+    res.json(payload)
+  }))
+
+  router.get('/pinokio/resource/logs', asyncHandler(async (req, res) => {
+    const parsedRef = parsePinokioRef(typeof req.query.ref === 'string' ? req.query.ref : '')
+    if (!parsedRef.valid) {
+      res.status(400).json({ error: parsedRef.error || 'Invalid ref' })
+      return
+    }
+    if (parsedRef.scope !== 'api') {
+      res.status(400).json({ error: `Unsupported ref scope: ${parsedRef.scope}` })
+      return
+    }
+    const canonicalRef = buildPinokioRef(parsedRef)
+    if (!isLocalPinokioRef(parsedRef)) {
+      try {
+        const params = { ref: canonicalRef }
+        if (typeof req.query.script === 'string' && req.query.script.trim()) {
+          params.script = req.query.script
+        }
+        const tail = registry.parseTailCount(req.query.tail, 200)
+        if (Number.isFinite(tail) && tail > 0) {
+          params.tail = String(tail)
+        }
+        const response = await axios.get(`http://${parsedRef.host}:${parsedRef.port}/pinokio/resource/logs`, {
+          timeout: DEFAULT_PEER_TIMEOUT_MS,
+          headers: peerRequestHeaders(req),
+          params
+        })
+        const payload = response && response.data && typeof response.data === 'object'
+          ? { ...response.data }
+          : {}
+        payload.app_id = parsedRef.id
+        payload.ref = canonicalRef
+        payload.source = buildSource(parsedRef.host, false)
+        res.json(payload)
+        return
+      } catch (error) {
+        if (error && error.response) {
+          res.status(error.response.status).json(error.response.data)
+          return
+        }
+        res.status(502).json({
+          error: 'Peer resource logs unavailable',
+          ref: canonicalRef,
+          source: buildSource(parsedRef.host, false)
+        })
+        return
+      }
+    }
+    const appId = registry.normalizeAppId(parsedRef.id)
+    if (!appId) {
+      res.status(400).json({ error: 'Invalid app_id', ref: canonicalRef })
+      return
+    }
+    const status = await registry.buildAppStatus(appId, {
+      source: req.$source || null
+    })
+    if (!status) {
+      res.status(404).json({ error: 'App not found', ref: canonicalRef })
+      return
+    }
+    const tail = registry.parseTailCount(req.query.tail, 200)
+    const scriptQuery = typeof req.query.script === 'string' ? req.query.script : ''
+    const resolvedLog = await appLogs.resolveAppLogFile(status.path, scriptQuery, status.running_scripts)
+    if (resolvedLog && resolvedLog.error === 'INVALID_SCRIPT') {
+      res.status(400).json({ error: 'Invalid script path', ref: canonicalRef })
+      return
+    }
+    if (!resolvedLog || !resolvedLog.file) {
+      res.status(404).json({
+        error: 'No log file found',
+        ref: canonicalRef,
+        script: scriptQuery || null
+      })
+      return
+    }
+    const logData = await appLogs.readLogTail(resolvedLog.file, tail)
+    res.json({
+      app_id: appId,
+      ref: canonicalRef,
+      source: buildSource(currentPeerHost(), true),
+      script: resolvedLog.script,
+      file: registry.toPosixRelative(status.path, resolvedLog.file),
+      ...logData
+    })
+  }))
+
+  router.post('/pinokio/resource/upload', upload.any(), asyncHandler(async (req, res) => {
+    const rawRef = typeof req.query.ref === 'string' && req.query.ref.trim()
+      ? req.query.ref
+      : (req.body && typeof req.body.ref === 'string' ? req.body.ref : '')
+    const parsedRef = parsePinokioRef(rawRef)
+    if (!parsedRef.valid) {
+      res.status(400).json({ error: parsedRef.error || 'Invalid ref' })
+      return
+    }
+    if (parsedRef.scope !== 'api') {
+      res.status(400).json({ error: `Unsupported ref scope: ${parsedRef.scope}` })
+      return
+    }
+    const canonicalRef = buildPinokioRef(parsedRef)
+    const files = Array.isArray(req.files) ? req.files : []
+    if (files.length === 0) {
+      res.status(400).json({ error: 'No files provided', ref: canonicalRef })
+      return
+    }
+    if (!isLocalPinokioRef(parsedRef)) {
+      try {
+        const form = new FormData()
+        for (const file of files) {
+          if (!file || !file.buffer) {
+            continue
+          }
+          form.append('files', file.buffer, {
+            filename: path.basename(file.originalname || 'upload'),
+            contentType: file.mimetype || 'application/octet-stream',
+            knownLength: typeof file.size === 'number' ? file.size : file.buffer.length
+          })
+        }
+        const response = await axios.post(`http://${parsedRef.host}:${parsedRef.port}/pinokio/resource/upload`, form, {
+          timeout: DEFAULT_PEER_UPLOAD_TIMEOUT_MS,
+          maxBodyLength: Infinity,
+          maxContentLength: Infinity,
+          headers: {
+            ...peerRequestHeaders(req),
+            ...form.getHeaders()
+          },
+          params: {
+            ref: canonicalRef
+          }
+        })
+        const payload = response && response.data && typeof response.data === 'object'
+          ? { ...response.data }
+          : {}
+        payload.app_id = parsedRef.id
+        payload.ref = canonicalRef
+        payload.source = buildSource(parsedRef.host, false)
+        res.json(payload)
+        return
+      } catch (error) {
+        if (error && error.response) {
+          res.status(error.response.status).json(error.response.data)
+          return
+        }
+        res.status(502).json({
+          error: 'Peer resource upload unavailable',
+          ref: canonicalRef,
+          source: buildSource(parsedRef.host, false)
+        })
+        return
+      }
+    }
+    const appId = registry.normalizeAppId(parsedRef.id)
+    if (!appId) {
+      res.status(400).json({ error: 'Invalid app_id', ref: canonicalRef })
+      return
+    }
+    const status = await registry.buildAppStatus(appId, {
+      source: req.$source || null
+    })
+    if (!status || !status.path) {
+      res.status(404).json({ error: 'App not found', ref: canonicalRef })
+      return
+    }
+    const payload = await storeAppUploads(status.path, files)
+    if (!Array.isArray(payload.files) || payload.files.length === 0) {
+      res.status(400).json({ error: 'No valid files provided', ref: canonicalRef })
+      return
+    }
+    const decorated = decorateUploadResult(payload, buildSource(currentPeerHost(), true), appId, {
+      host: parsedRef.host,
+      port: parsedRef.port
+    })
+    decorated.app_id = appId
+    decorated.ref = canonicalRef
+    res.json(decorated)
+  }))
+
   router.get('/apps/search', asyncHandler(async (req, res) => {
     const q = typeof req.query.q === 'string' ? req.query.q : ''
     const mode = typeof req.query.mode === 'string' ? req.query.mode : ''
@@ -600,6 +971,12 @@ module.exports = function registerAppRoutes(app, { registry, preferences, appSea
           : {}
         payload.app_id = qualifyAppId(requestedAppId, remoteHost)
         payload.source = buildSource(remoteHost, false)
+        payload.ref = buildPinokioRef({
+          host: remoteHost,
+          port: peerPort(),
+          scope: 'api',
+          id: requestedAppId
+        })
         res.json(payload)
         return
       } catch (error) {
@@ -645,6 +1022,12 @@ module.exports = function registerAppRoutes(app, { registry, preferences, appSea
     const logData = await appLogs.readLogTail(resolvedLog.file, tail)
     res.json({
       app_id: appId,
+      ref: buildPinokioRef({
+        host: currentPeerHost() || '127.0.0.1',
+        port: peerPort(),
+        scope: 'api',
+        id: appId
+      }),
       script: resolvedLog.script,
       source: resolvedLog.source,
       file: registry.toPosixRelative(status.path, resolvedLog.file),