poi-plugin-mcp 0.2.12 → 0.2.13

package/README.md

@@ -23,20 +23,16 @@ Then restart Poi and enable `MCP Data Bridge` if needed.
 
 ## Development Install
 
-When working from this repository, install from the repo root:
+When working from this repository, verify the package from the repo root:
 
 ```powershell
 npm install
-npm run install:poi
+npm test
+npm pack --dry-run --ignore-scripts
 ```
 
-Then restart Poi and enable `MCP Data Bridge` if needed.
-
-The installer creates:
-
-```text
-%APPDATA%\poi\plugins\node_modules\poi-plugin-mcp -> <repo>\packages\poi-plugin-mcp
-```
+Publish or install the generated package through Poi's plugin manager. Fully
+exit Poi before a manual npm installation into its plugin directory.
 
 ## Settings
 
@@ -64,6 +60,8 @@ token is never returned by an HTTP endpoint.
 | `/quest-list` | Latest complete quest-page telemetry |
 | `/quest-action` | Latest successful quest start or stop request |
 | `/equipment-action` | Latest successful equipment mutation request |
+| `/fleet-action` | Latest successful fleet-position mutation request |
+| `/action-events` | Bounded generic KanColle API action-event stream |
 | `/airbase` | Land base air squadron data |
 | `/names` | Ship, equipment, and mission name maps |
 | `/master` | Master ship, equipment, ship type, equipment type, mission, and bounded equipment compatibility data |
@@ -72,6 +70,7 @@ token is never returned by an HTTP endpoint.
 | `/battle` | Observed battle packets, official settlement, and compact Prophet state |
 | `/screenshot` | In-memory PNG capture of the game WebView |
 | `/input/status` | Whether authenticated WebView input is enabled |
+| `/input/lease/*` | Acquire, renew, release, inspect, or revoke the one input lease |
 | `/input` | Authenticated, serialized WebView input |
 | `/all` | Combined basic runtime data |
 
@@ -83,10 +82,11 @@ MCP resources and tools. Its response disables CORS and uses
 
 ### WebView Input
 
-`GET /input/status` returns only `{"enabled":true|false}`. `POST /input`
-requires `Authorization: Bearer <token>`, accepts at most 64 KiB of JSON, and
-works only while WebView input is enabled in the plugin settings. Both routes
-disable CORS and return `Cache-Control: no-store`.
+`GET /input/status` returns only `{"enabled":true|false}`. Input requires both
+`Authorization: Bearer <token>` and one active expiring lease. A static token
+alone cannot authorize `POST /input`. Requests accept at most 64 KiB of JSON
+and work only while WebView input is enabled in the plugin settings. Input
+routes disable CORS and return `Cache-Control: no-store`.
 
 Each POST accepts exactly one operation:
 
@@ -97,6 +97,13 @@ Each POST accepts exactly one operation:
 Click coordinates use a canonical 1200x720 layout and are scaled to Poi's
 current game WebView. Supported buttons are `left`, `middle`, and `right`.
 
+```json
+{"operation":"drag","fromX":247,"fromY":178,"toX":202,"toY":178,"durationMs":400,"button":"left"}
+```
+
+Drag endpoints use the same canonical layout. Duration must be from 50 through
+2000 milliseconds.
+
 ```json
 {"operation":"key","event":"keyDown","key":"Enter"}
 ```

package/index.js

@@ -8,6 +8,7 @@ const controller = createBridgeController({
   getQuestAction: telemetry.getQuestAction,
   getEquipmentAction: telemetry.getEquipmentAction,
   getFleetAction: telemetry.getFleetAction,
+  getActionEvents: telemetry.getActionEvents,
   getBattleTelemetry: telemetry.getBattleTelemetry,
 })
 const settingsClass = createSettingsClass(controller)

package/lib/bridge-controller.js

@@ -34,6 +34,7 @@ function createBridgeController(options = {}) {
       getQuestAction: options.getQuestAction,
       getEquipmentAction: options.getEquipmentAction,
       getFleetAction: options.getFleetAction,
+      getActionEvents: options.getActionEvents,
       getBattleTelemetry: options.getBattleTelemetry,
       inputEnabled: settings.inputEnabled,
       inputToken,

package/lib/poi-action-events.js

@@ -0,0 +1,288 @@
+const crypto = require('node:crypto')
+
+const DEFAULT_CAPACITY = 256
+const DEFAULT_LIMIT = 64
+const MAX_CAPACITY = 256
+const MAX_OBJECT_KEYS = 32
+const MAX_ARRAY_ITEMS = 16
+const MAX_STRING_LENGTH = 256
+const MAX_RESPONSE_DEPTH = 4
+
+const EXACT_PATHS = new Set([
+  '/kcsapi/api_start2/getData',
+  '/kcsapi/api_port/port',
+  '/kcsapi/api_get_member/base_air_corps',
+  '/kcsapi/api_get_member/deck',
+  '/kcsapi/api_get_member/kdock',
+  '/kcsapi/api_get_member/mapinfo',
+  '/kcsapi/api_get_member/material',
+  '/kcsapi/api_get_member/ndock',
+  '/kcsapi/api_get_member/practice',
+  '/kcsapi/api_get_member/questlist',
+  '/kcsapi/api_get_member/ship2',
+  '/kcsapi/api_get_member/ship3',
+  '/kcsapi/api_get_member/slot_item',
+  '/kcsapi/api_get_member/useitem',
+  '/kcsapi/api_req_air_corps/set_action',
+  '/kcsapi/api_req_air_corps/set_plane',
+  '/kcsapi/api_req_air_corps/supply',
+  '/kcsapi/api_req_battle_midnight/battle',
+  '/kcsapi/api_req_battle_midnight/sp_midnight',
+  '/kcsapi/api_req_hensei/change',
+  '/kcsapi/api_req_hensei/combined',
+  '/kcsapi/api_req_hensei/preset_select',
+  '/kcsapi/api_req_hokyu/charge',
+  '/kcsapi/api_req_kaisou/powerup',
+  '/kcsapi/api_req_kaisou/slot_deprive',
+  '/kcsapi/api_req_kaisou/slotset',
+  '/kcsapi/api_req_kaisou/slotset_ex',
+  '/kcsapi/api_req_kaisou/unsetslot_all',
+  '/kcsapi/api_req_kousyou/createitem',
+  '/kcsapi/api_req_kousyou/createship',
+  '/kcsapi/api_req_kousyou/createship_speedchange',
+  '/kcsapi/api_req_kousyou/destroyitem2',
+  '/kcsapi/api_req_kousyou/destroyship',
+  '/kcsapi/api_req_kousyou/getship',
+  '/kcsapi/api_req_kousyou/remodel_slot',
+  '/kcsapi/api_req_map/next',
+  '/kcsapi/api_req_map/select_eventmap_rank',
+  '/kcsapi/api_req_map/start',
+  '/kcsapi/api_req_member/get_practice_enemyinfo',
+  '/kcsapi/api_req_mission/result',
+  '/kcsapi/api_req_mission/start',
+  '/kcsapi/api_req_nyukyo/speedchange',
+  '/kcsapi/api_req_nyukyo/start',
+  '/kcsapi/api_req_practice/battle',
+  '/kcsapi/api_req_practice/battle_result',
+  '/kcsapi/api_req_practice/midnight_battle',
+  '/kcsapi/api_req_quest/clearitemget',
+  '/kcsapi/api_req_quest/start',
+  '/kcsapi/api_req_quest/stop',
+])
+
+const ALLOWED_PREFIXES = [
+  '/kcsapi/api_req_sortie/',
+  '/kcsapi/api_req_combined_battle/',
+]
+
+const SHARED_TELEMETRY_TIMESTAMP_PATHS = new Set([
+  '/kcsapi/api_get_member/questlist',
+  '/kcsapi/api_req_quest/start',
+  '/kcsapi/api_req_quest/stop',
+  '/kcsapi/api_req_kaisou/slotset',
+  '/kcsapi/api_req_kaisou/slotset_ex',
+  '/kcsapi/api_req_kaisou/slot_deprive',
+  '/kcsapi/api_req_kaisou/unsetslot_all',
+  '/kcsapi/api_req_hensei/change',
+])
+
+function createPoiActionEvents(options = {}) {
+  const now = options.now || (() => new Date())
+  const inferredNow = options.inferredNow || (() => new Date())
+  const sessionId = boundedId(options.sessionId || crypto.randomUUID(), 'sessionId')
+  const capacity = boundedInteger(
+    options.capacity == null ? DEFAULT_CAPACITY : options.capacity,
+    1,
+    MAX_CAPACITY,
+    'capacity',
+  )
+  const events = []
+  let latestGeneration = 0
+
+  function capture(detail) {
+    if (!isCapturableDetail(detail)) return null
+    const explicitApiResult = readApiResult(detail)
+    const apiResult = explicitApiResult == null && hasUnwrappedResponseBody(detail)
+      ? 1
+      : explicitApiResult
+    if (apiResult !== 1) return null
+
+    latestGeneration += 1
+    const eventNow = explicitApiResult != null ||
+      SHARED_TELEMETRY_TIMESTAMP_PATHS.has(detail.path)
+      ? now
+      : inferredNow
+    const event = Object.freeze({
+      generation: latestGeneration,
+      capturedAt: timestamp(eventNow()),
+      path: detail.path,
+      apiResult,
+      postBody: sanitizePostBody(detail.postBody),
+      responseSummary: sanitizeResponse(detail.body),
+    })
+    events.push(event)
+    if (events.length > capacity) events.splice(0, events.length - capacity)
+    return event
+  }
+
+  function read(options = {}) {
+    const after = boundedInteger(
+      options.after == null ? 0 : options.after,
+      0,
+      Number.MAX_SAFE_INTEGER,
+      'after',
+    )
+    const limit = boundedInteger(
+      options.limit == null ? DEFAULT_LIMIT : options.limit,
+      1,
+      MAX_CAPACITY,
+      'limit',
+    )
+    return {
+      available: true,
+      sessionId,
+      latestGeneration,
+      events: events
+        .filter((event) => event.generation > after)
+        .slice(0, limit),
+    }
+  }
+
+  return Object.freeze({ capture, read })
+}
+
+function isCapturableDetail(detail) {
+  return Boolean(
+    detail &&
+    typeof detail === 'object' &&
+    !Array.isArray(detail) &&
+    typeof detail.path === 'string' &&
+    (
+      EXACT_PATHS.has(detail.path) ||
+      ALLOWED_PREFIXES.some((prefix) => detail.path.startsWith(prefix))
+    ),
+  )
+}
+
+function readApiResult(detail) {
+  const candidates = [
+    detail.apiResult,
+    detail.api_result,
+    detail.result,
+    detail.body && detail.body.api_result,
+  ]
+  for (const candidate of candidates) {
+    if (candidate == null || candidate === '') continue
+    const parsed = Number(candidate)
+    return Number.isInteger(parsed) ? parsed : null
+  }
+  return null
+}
+
+function hasUnwrappedResponseBody(detail) {
+  if (!Object.prototype.hasOwnProperty.call(detail, 'body')) return false
+  const body = detail.body
+  if (!isPlainObject(body) && !Array.isArray(body)) return false
+  return !(
+    isPlainObject(body) &&
+    (
+      Object.prototype.hasOwnProperty.call(body, 'api_result') ||
+      Object.prototype.hasOwnProperty.call(body, 'api_data')
+    )
+  )
+}
+
+function sanitizePostBody(value) {
+  if (!isPlainObject(value)) return {}
+  const output = {}
+  for (const [key, item] of Object.entries(value).slice(0, MAX_OBJECT_KEYS)) {
+    if (!safeKey(key)) continue
+    const scalar = sanitizeScalar(item)
+    if (scalar !== undefined) {
+      output[key] = scalar
+      continue
+    }
+    if (
+      Array.isArray(item) &&
+      item.length <= MAX_ARRAY_ITEMS
+    ) {
+      const array = item.map(sanitizeScalar)
+      if (array.every((entry) => entry !== undefined)) output[key] = array
+    }
+  }
+  return output
+}
+
+function sanitizeResponse(value) {
+  const sanitized = sanitizeNested(value, 0)
+  return isPlainObject(sanitized) ? sanitized : {}
+}
+
+function sanitizeNested(value, depth) {
+  const scalar = sanitizeScalar(value)
+  if (scalar !== undefined) return scalar
+  if (depth >= MAX_RESPONSE_DEPTH) return undefined
+  if (Array.isArray(value)) {
+    return value
+      .slice(0, MAX_ARRAY_ITEMS)
+      .map((item) => sanitizeNested(item, depth + 1))
+      .filter((item) => item !== undefined)
+  }
+  if (!isPlainObject(value)) return undefined
+  const output = {}
+  for (const [key, item] of Object.entries(value).slice(0, MAX_OBJECT_KEYS)) {
+    if (!safeKey(key)) continue
+    const sanitized = sanitizeNested(item, depth + 1)
+    if (sanitized !== undefined) output[key] = sanitized
+  }
+  return output
+}
+
+function sanitizeScalar(value) {
+  if (
+    value === null ||
+    typeof value === 'boolean' ||
+    (typeof value === 'number' && Number.isFinite(value))
+  ) {
+    return value
+  }
+  if (typeof value === 'string') return value.slice(0, MAX_STRING_LENGTH)
+  return undefined
+}
+
+function safeKey(key) {
+  return (
+    typeof key === 'string' &&
+    key.length > 0 &&
+    key.length <= 64 &&
+    !/(authorization|cookie|header|password|secret|token)/i.test(key)
+  )
+}
+
+function timestamp(value) {
+  const date = value instanceof Date ? value : new Date(value)
+  if (!Number.isFinite(date.getTime())) throw new Error('now must return a valid date')
+  return date.toISOString()
+}
+
+function boundedId(value, name) {
+  if (typeof value !== 'string' || value.length === 0 || value.length > 256) {
+    throw new Error(`${name} must be a non-empty bounded string`)
+  }
+  return value
+}
+
+function boundedInteger(value, minimum, maximum, name) {
+  if (
+    !Number.isSafeInteger(value) ||
+    value < minimum ||
+    value > maximum
+  ) {
+    throw new Error(
+      `${name} must be an integer from ${minimum} through ${maximum}`,
+    )
+  }
+  return value
+}
+
+function isPlainObject(value) {
+  return Boolean(
+    value &&
+    typeof value === 'object' &&
+    !Array.isArray(value),
+  )
+}
+
+module.exports = {
+  createPoiActionEvents,
+}

package/lib/poi-http-bridge.js

@@ -6,6 +6,7 @@ const path = require('path')
 const packageJson = require('../package.json')
 const { loadOrCreateInputToken } = require('./input-token')
 const { createPoiInputProvider } = require('./poi-input')
+const { createPoiInputLease } = require('./poi-input-lease')
 const { createPoiScreenshotProvider } = require('./poi-screenshot')
 
 const DEFAULT_PORT = 17777
@@ -25,6 +26,8 @@ const JSONRPC_VERSION = '2.0'
 const MCP_PROTOCOL_VERSION = '2024-11-05'
 const INPUT_BODY_LIMIT = 64 * 1024
 const MASTER_FILE_LIMIT = 16 * 1024 * 1024
+const DEFAULT_ACTION_EVENT_LIMIT = 64
+const MAX_ACTION_EVENT_LIMIT = 256
 
 function createPoiDataBridge(options = {}) {
   const getStore = options.getStore || defaultGetStore
@@ -39,19 +42,26 @@ function createPoiDataBridge(options = {}) {
     (() => ({ available: false, generation: 0 }))
   const getFleetAction = options.getFleetAction ||
     (() => ({ available: false, generation: 0 }))
+  const getActionEvents = options.getActionEvents ||
+    (() => ({
+      available: false,
+      sessionId: null,
+      latestGeneration: 0,
+      events: [],
+    }))
   const getBattleTelemetry = options.getBattleTelemetry ||
     (() => ({ available: false, generation: 0 }))
   const inputEnabled = options.inputEnabled === true
   const inputToken = options.inputToken || (
     inputEnabled ? loadOrCreateInputToken(options.inputTokenFile) : null
   )
+  const inputLease = options.inputLease || createPoiInputLease(options.inputLeaseOptions)
   let captureScreenshot = options.captureScreenshot || null
   let performInput = options.performInput || null
 
   let server = null
   let actualPort = 0
   let inputPending = Promise.resolve()
-  let inputSequence = 0
 
   function readStore() {
     const store = getStore()
@@ -84,17 +94,22 @@ function createPoiDataBridge(options = {}) {
     })
   }
 
-  function enqueueInput(operation) {
+  function enqueueInput(operation, claim) {
     const execute = async () => {
+      inputLease.assertClaimActive(claim)
       if (!performInput) {
         performInput = createPoiInputProvider({ getStore })
       }
       const operationName = await performInput(operation)
-      inputSequence += 1
       return {
         ok: true,
         operation: operationName,
-        sequence: inputSequence,
+        sequence: claim.sequence,
+        leaseId: claim.leaseId,
+        ownerSessionId: claim.ownerSessionId,
+        runId: claim.runId,
+        action: claim.action,
+        acceptedAt: claim.acceptedAt,
       }
     }
     const result = inputPending.then(execute, execute)
@@ -136,14 +151,92 @@ function createPoiDataBridge(options = {}) {
         'Input request body exceeds 64KB.',
       )
       const operation = JSON.parse(body || '{}')
-      sendInputJson(res, 200, await enqueueInput(operation))
+      const { input, claim } = claimInputOperation(inputLease, operation)
+      sendInputJson(res, 200, await enqueueInput(input, claim))
     } catch (error) {
-      const statusCode = error.code === 'BODY_TOO_LARGE'
+      const statusCode = error.statusCode || (error.code === 'BODY_TOO_LARGE'
         ? 413
         : /WebView|dimensions/.test(error.message)
           ? 503
-          : 400
-      sendInputJson(res, statusCode, { error: error.message })
+          : 400)
+      sendInputJson(res, statusCode, {
+        ...(error.code ? { code: error.code } : {}),
+        error: error.message,
+      })
+    }
+  }
+
+  async function handleInputLeaseRequest(req, res, endpoint) {
+    if (!hasValidBearerToken(req.headers.authorization, inputToken)) {
+      drainRequest(req)
+      sendInputJson(
+        res,
+        401,
+        { error: 'A valid Bearer token is required.' },
+        { headers: { 'WWW-Authenticate': 'Bearer' } },
+      )
+      return
+    }
+    if (endpoint === '/input/lease') {
+      if (req.method !== 'GET') {
+        drainRequest(req)
+        sendInputJson(res, 405, { error: 'Input lease status only accepts GET requests.' })
+        return
+      }
+      const lease = inputLease.status()
+      sendInputJson(res, 200, { active: lease !== null, lease })
+      return
+    }
+    if (req.method !== 'POST') {
+      drainRequest(req)
+      sendInputJson(res, 405, { error: 'Input lease changes only accept POST requests.' })
+      return
+    }
+    if (!inputEnabled) {
+      drainRequest(req)
+      sendInputJson(res, 403, { error: 'WebView input is disabled.' })
+      return
+    }
+    if (requestContentLength(req) > INPUT_BODY_LIMIT) {
+      drainRequest(req)
+      sendInputJson(res, 413, { error: 'Input request body exceeds 64KB.' })
+      return
+    }
+
+    try {
+      const body = await readRequestBody(
+        req,
+        INPUT_BODY_LIMIT,
+        'Input request body exceeds 64KB.',
+      )
+      const request = JSON.parse(body || '{}')
+      if (endpoint === '/input/lease/acquire') {
+        const lease = inputLease.acquire(request)
+        sendInputJson(res, 200, { active: true, lease })
+        return
+      }
+      if (endpoint === '/input/lease/renew') {
+        const lease = inputLease.renew(request)
+        sendInputJson(res, 200, { active: true, lease })
+        return
+      }
+      if (endpoint === '/input/lease/release') {
+        inputLease.release(request)
+        sendInputJson(res, 200, { active: false, released: true })
+        return
+      }
+      if (endpoint === '/input/lease/revoke') {
+        inputLease.revoke(request)
+        sendInputJson(res, 200, { active: false, revoked: true })
+        return
+      }
+      sendInputJson(res, 404, { error: `Unknown input lease endpoint: ${endpoint}` })
+    } catch (error) {
+      const statusCode = error.statusCode || (error.code === 'BODY_TOO_LARGE' ? 413 : 400)
+      sendInputJson(res, statusCode, {
+        ...(error.code ? { code: error.code } : {}),
+        error: error.message,
+      })
     }
   }
 
@@ -182,7 +275,11 @@ function createPoiDataBridge(options = {}) {
         return
       }
 
-      const endpoint = new URL(req.url, `http://127.0.0.1:${actualPort || configuredPort}`).pathname
+      const requestUrl = new URL(
+        req.url,
+        `http://127.0.0.1:${actualPort || configuredPort}`,
+      )
+      const endpoint = requestUrl.pathname
 
       if (endpoint === '/health') {
         sendJson(res, 200, { status: 'ok' })
@@ -239,6 +336,17 @@ function createPoiDataBridge(options = {}) {
         return
       }
 
+      if (
+        endpoint === '/input/lease' ||
+        endpoint === '/input/lease/acquire' ||
+        endpoint === '/input/lease/renew' ||
+        endpoint === '/input/lease/release' ||
+        endpoint === '/input/lease/revoke'
+      ) {
+        await handleInputLeaseRequest(req, res, endpoint)
+        return
+      }
+
       if (endpoint === '/input') {
         await handleInputRequest(req, res)
         return
@@ -264,6 +372,31 @@ function createPoiDataBridge(options = {}) {
         return
       }
 
+      if (endpoint === '/action-events') {
+        if (req.method !== 'GET') {
+          drainRequest(req)
+          sendJson(res, 405, {
+            error: 'Action events endpoint only accepts GET requests.',
+          })
+          return
+        }
+        sendJson(res, 200, getActionEvents({
+          after: clampedQueryInteger(
+            requestUrl.searchParams.get('after'),
+            0,
+            0,
+            Number.MAX_SAFE_INTEGER,
+          ),
+          limit: clampedQueryInteger(
+            requestUrl.searchParams.get('limit'),
+            DEFAULT_ACTION_EVENT_LIMIT,
+            1,
+            MAX_ACTION_EVENT_LIMIT,
+          ),
+        }))
+        return
+      }
+
       const store = readStore()
       const info = store.info
 
@@ -322,6 +455,11 @@ function createPoiDataBridge(options = {}) {
               records: (info.quests && info.quests.records) || {},
             },
             airbase: info.airbase || [],
+            repairs: info.repairs || [],
+            constructions: info.constructions || [],
+            maps: info.maps || {},
+            useitems: info.useitems || {},
+            sortie: store.sortie || {},
             names: extractNames(store),
           })
           break
@@ -385,6 +523,53 @@ function createPoiDataBridge(options = {}) {
   }
 }
 
+function clampedQueryInteger(value, fallback, minimum, maximum) {
+  if (value == null || value === '') return fallback
+  const parsed = Number(value)
+  if (!Number.isFinite(parsed)) return fallback
+  return Math.min(maximum, Math.max(minimum, Math.trunc(parsed)))
+}
+
+function claimInputOperation(inputLease, request) {
+  if (!request || typeof request !== 'object' || Array.isArray(request)) {
+    throw inputBridgeError('INPUT_LEASE_REQUIRED', 'Input lease fields are required.', 409)
+  }
+  const {
+    leaseId,
+    ownerSessionId,
+    runId,
+    action,
+    sequence,
+    ...input
+  } = request
+  if (
+    typeof leaseId !== 'string' ||
+    typeof ownerSessionId !== 'string' ||
+    typeof runId !== 'string' ||
+    typeof action !== 'string' ||
+    !Number.isSafeInteger(sequence)
+  ) {
+    throw inputBridgeError('INPUT_LEASE_REQUIRED', 'Input lease fields are required.', 409)
+  }
+  return {
+    input,
+    claim: inputLease.consumeInput({
+      leaseId,
+      ownerSessionId,
+      runId,
+      action,
+      sequence,
+    }),
+  }
+}
+
+function inputBridgeError(code, message, statusCode) {
+  const error = new Error(message)
+  error.code = code
+  error.statusCode = statusCode
+  return error
+}
+
 function readRequestBody(
   req,
   maxBytes = 1024 * 1024,
@@ -631,6 +816,11 @@ function readBridgeData(endpoint, readStore, plannerFile) {
           records: (info.quests && info.quests.records) || {},
         },
         airbase: info.airbase || [],
+        repairs: info.repairs || [],
+        constructions: info.constructions || [],
+        maps: info.maps || {},
+        useitems: info.useitems || {},
+        sortie: store.sortie || {},
         names: extractNames(store),
       }
     default:

package/lib/poi-input-lease.js

@@ -0,0 +1,226 @@
+const crypto = require('node:crypto')
+
+const DEFAULT_TTL_MS = 10_000
+const MAX_TTL_MS = 30_000
+const MAX_ID_LENGTH = 256
+
+function createPoiInputLease(options = {}) {
+  const now = options.now || Date.now
+  const createId = options.createId || crypto.randomUUID
+  const defaultTtlMs = positiveInteger(
+    options.defaultTtlMs == null ? DEFAULT_TTL_MS : options.defaultTtlMs,
+    'defaultTtlMs',
+  )
+  const maxTtlMs = positiveInteger(
+    options.maxTtlMs == null ? MAX_TTL_MS : options.maxTtlMs,
+    'maxTtlMs',
+  )
+  if (defaultTtlMs > maxTtlMs) {
+    throw new Error('defaultTtlMs must not exceed maxTtlMs')
+  }
+
+  let active = null
+
+  function current() {
+    if (active && active.expiresAtMs <= now()) {
+      active = null
+    }
+    return active
+  }
+
+  function status() {
+    const lease = current()
+    return lease ? publicLease(lease) : null
+  }
+
+  function acquire(request) {
+    if (current()) {
+      throw leaseError('INPUT_LEASE_BUSY', 'Another input lease is active.')
+    }
+    const normalized = normalizeAcquireRequest(request, defaultTtlMs, maxTtlMs)
+    const leaseId = boundedId(createId(), 'leaseId')
+    active = {
+      leaseId,
+      ownerSessionId: normalized.ownerSessionId,
+      runId: normalized.runId,
+      mode: normalized.mode,
+      action: normalized.action,
+      expiresAtMs: now() + normalized.ttlMs,
+      nextSequence: 1,
+    }
+    return publicLease(active)
+  }
+
+  function renew(request) {
+    const lease = requireMatchingLease(request)
+    const ttlMs = normalizeTtl(request && request.ttlMs, defaultTtlMs, maxTtlMs)
+    lease.expiresAtMs = now() + ttlMs
+    return publicLease(lease)
+  }
+
+  function release(request) {
+    requireMatchingLease(request)
+    active = null
+    return true
+  }
+
+  function revoke(request) {
+    const lease = current()
+    if (!lease) {
+      throw leaseError('INPUT_LEASE_REQUIRED', 'No input lease is active.')
+    }
+    if (boundedId(request && request.leaseId, 'leaseId') !== lease.leaseId) {
+      throw leaseError('INPUT_LEASE_MISMATCH', 'Input lease identity does not match.')
+    }
+    active = null
+    return true
+  }
+
+  function consumeInput(request) {
+    const lease = requireMatchingLease(request)
+    const action = boundedId(request && request.action, 'action')
+    if (lease.mode === 'action' && action !== lease.action) {
+      throw leaseError(
+        'INPUT_LEASE_ACTION_MISMATCH',
+        `Input action ${action} does not match lease action ${lease.action}.`,
+      )
+    }
+    const sequence = request && request.sequence
+    if (!Number.isSafeInteger(sequence) || sequence !== lease.nextSequence) {
+      throw leaseError(
+        'INPUT_SEQUENCE_MISMATCH',
+        `Input sequence must be ${lease.nextSequence}.`,
+      )
+    }
+    lease.nextSequence += 1
+    return Object.freeze({
+      leaseId: lease.leaseId,
+      ownerSessionId: lease.ownerSessionId,
+      runId: lease.runId,
+      action,
+      sequence,
+      acceptedAt: new Date(now()).toISOString(),
+    })
+  }
+
+  function assertClaimActive(claim) {
+    const lease = requireMatchingLease(claim)
+    const action = boundedId(claim && claim.action, 'action')
+    const sequence = claim && claim.sequence
+    if (
+      !Number.isSafeInteger(sequence) ||
+      sequence < 1 ||
+      sequence >= lease.nextSequence ||
+      (lease.mode === 'action' && action !== lease.action)
+    ) {
+      throw leaseError('INPUT_LEASE_MISMATCH', 'Input claim does not match the lease.')
+    }
+    return true
+  }
+
+  function requireMatchingLease(request) {
+    const lease = current()
+    if (!lease) {
+      throw leaseError('INPUT_LEASE_REQUIRED', 'No input lease is active.')
+    }
+    const leaseId = boundedId(request && request.leaseId, 'leaseId')
+    const ownerSessionId = boundedId(
+      request && request.ownerSessionId,
+      'ownerSessionId',
+    )
+    const runId = boundedId(request && request.runId, 'runId')
+    if (
+      lease.leaseId !== leaseId ||
+      lease.ownerSessionId !== ownerSessionId ||
+      lease.runId !== runId
+    ) {
+      throw leaseError('INPUT_LEASE_MISMATCH', 'Input lease identity does not match.')
+    }
+    return lease
+  }
+
+  return Object.freeze({
+    status,
+    acquire,
+    renew,
+    release,
+    revoke,
+    consumeInput,
+    assertClaimActive,
+  })
+}
+
+function normalizeAcquireRequest(request, defaultTtlMs, maxTtlMs) {
+  const ownerSessionId = boundedId(request && request.ownerSessionId, 'ownerSessionId')
+  const runId = boundedId(request && request.runId, 'runId')
+  const mode = request && request.mode
+  if (mode !== 'action' && mode !== 'workflow') {
+    throw leaseError('INVALID_INPUT_LEASE', 'Input lease mode must be action or workflow.')
+  }
+  const action = request && request.action
+  if (
+    (mode === 'action' && (typeof action !== 'string' || action.length === 0)) ||
+    (mode === 'workflow' && action !== null)
+  ) {
+    throw leaseError(
+      'INVALID_INPUT_LEASE',
+      'Action leases require an action and workflow leases require action null.',
+    )
+  }
+  return {
+    ownerSessionId,
+    runId,
+    mode,
+    action: mode === 'action' ? boundedId(action, 'action') : null,
+    ttlMs: normalizeTtl(request.ttlMs, defaultTtlMs, maxTtlMs),
+  }
+}
+
+function normalizeTtl(value, defaultTtlMs, maxTtlMs) {
+  const ttlMs = value == null ? defaultTtlMs : value
+  if (!Number.isSafeInteger(ttlMs) || ttlMs <= 0) {
+    throw leaseError('INVALID_INPUT_LEASE', 'Input lease ttlMs must be a positive integer.')
+  }
+  return Math.min(ttlMs, maxTtlMs)
+}
+
+function publicLease(lease) {
+  return Object.freeze({
+    leaseId: lease.leaseId,
+    ownerSessionId: lease.ownerSessionId,
+    runId: lease.runId,
+    mode: lease.mode,
+    action: lease.action,
+    expiresAt: new Date(lease.expiresAtMs).toISOString(),
+    nextSequence: lease.nextSequence,
+  })
+}
+
+function boundedId(value, name) {
+  if (
+    typeof value !== 'string' ||
+    value.length === 0 ||
+    value.length > MAX_ID_LENGTH
+  ) {
+    throw leaseError('INVALID_INPUT_LEASE', `${name} must be a non-empty string.`)
+  }
+  return value
+}
+
+function positiveInteger(value, name) {
+  if (!Number.isSafeInteger(value) || value <= 0) {
+    throw new Error(`${name} must be a positive integer`)
+  }
+  return value
+}
+
+function leaseError(code, message) {
+  const error = new Error(message)
+  error.code = code
+  error.statusCode = code === 'INVALID_INPUT_LEASE' ? 400 : 409
+  return error
+}
+
+module.exports = {
+  createPoiInputLease,
+}

package/lib/poi-input.js

@@ -1,6 +1,7 @@
 const CANONICAL_WIDTH = 1200
 const CANONICAL_HEIGHT = 720
 const DEFAULT_CLICK_DELAY_MS = 10
+const DRAG_MOVE_STEPS = 6
 const MAX_TEXT_LENGTH = 256
 
 const SUPPORTED_BUTTONS = new Set(['left', 'middle', 'right'])
@@ -48,6 +49,10 @@ function createPoiInputProvider(options = {}) {
         validateClick(operation)
         await sendClick(layout, operation, delay, clickDelayMs)
         return 'click'
+      case 'drag':
+        validateDrag(operation)
+        await sendDrag(layout, operation, delay)
+        return 'drag'
       case 'key':
         validateKey(operation)
         await layout.webContents.sendInputEvent({
@@ -129,6 +134,48 @@ function validateClick(operation) {
   }
 }
 
+function validateDrag(operation) {
+  assertExactFields(operation, [
+    'operation',
+    'fromX',
+    'fromY',
+    'toX',
+    'toY',
+    'durationMs',
+    'button',
+  ])
+  const coordinates = [
+    operation.fromX,
+    operation.fromY,
+    operation.toX,
+    operation.toY,
+  ]
+  if (coordinates.some((coordinate) => !Number.isFinite(coordinate))) {
+    throw new Error('Drag coordinates must be finite numbers')
+  }
+  if (
+    operation.fromX < 0 ||
+    operation.fromX >= CANONICAL_WIDTH ||
+    operation.toX < 0 ||
+    operation.toX >= CANONICAL_WIDTH ||
+    operation.fromY < 0 ||
+    operation.fromY >= CANONICAL_HEIGHT ||
+    operation.toY < 0 ||
+    operation.toY >= CANONICAL_HEIGHT
+  ) {
+    throw new Error('Drag coordinates must be within canonical bounds')
+  }
+  if (!Number.isInteger(operation.durationMs)) {
+    throw new Error('Drag durationMs must be an integer')
+  }
+  if (operation.durationMs < 50 || operation.durationMs > 2000) {
+    throw new Error('Drag durationMs must be from 50 to 2000')
+  }
+  if (!SUPPORTED_BUTTONS.has(operation.button)) {
+    throw new Error(`Unsupported mouse button: ${String(operation.button)}`)
+  }
+}
+
 function validateKey(operation) {
   assertExactFields(operation, ['operation', 'event', 'key'])
   if (!SUPPORTED_KEY_EVENTS.has(operation.event)) {
@@ -181,6 +228,56 @@ async function sendClick(layout, operation, delay, clickDelayMs) {
   }
 }
 
+async function sendDrag(layout, operation, delay) {
+  const start = {
+    x: Math.floor((operation.fromX * layout.width) / CANONICAL_WIDTH),
+    y: Math.floor((operation.fromY * layout.height) / CANONICAL_HEIGHT),
+  }
+  const destination = {
+    x: Math.floor((operation.toX * layout.width) / CANONICAL_WIDTH),
+    y: Math.floor((operation.toY * layout.height) / CANONICAL_HEIGHT),
+  }
+  const mouseButton = { button: operation.button }
+
+  await layout.webContents.sendInputEvent({
+    type: 'mouseMove',
+    ...start,
+    ...mouseButton,
+  })
+  try {
+    await layout.webContents.sendInputEvent({
+      type: 'mouseDown',
+      ...start,
+      ...mouseButton,
+      clickCount: 1,
+    })
+    for (let step = 1; step <= DRAG_MOVE_STEPS; step += 1) {
+      const elapsed = Math.round((operation.durationMs * step) / DRAG_MOVE_STEPS)
+      const previousElapsed = Math.round(
+        (operation.durationMs * (step - 1)) / DRAG_MOVE_STEPS,
+      )
+      await delay(elapsed - previousElapsed)
+      await layout.webContents.sendInputEvent({
+        type: 'mouseMove',
+        x: Math.round(
+          start.x + ((destination.x - start.x) * step) / DRAG_MOVE_STEPS,
+        ),
+        y: Math.round(
+          start.y + ((destination.y - start.y) * step) / DRAG_MOVE_STEPS,
+        ),
+        ...mouseButton,
+      })
+    }
+  } finally {
+    await layout.webContents.sendInputEvent({
+      type: 'mouseUp',
+      ...destination,
+      ...mouseButton,
+      clickCount: 1,
+    })
+  }
+}
+
 function defaultDelay(milliseconds) {
   return new Promise((resolve) => setTimeout(resolve, milliseconds))
 }

package/lib/poi-telemetry.js

@@ -1,3 +1,5 @@
+const { createPoiActionEvents } = require('./poi-action-events')
+
 const QUEST_LIST_PATH = '/kcsapi/api_get_member/questlist'
 const QUEST_ACTION_PATHS = new Set([
   '/kcsapi/api_req_quest/start',
@@ -40,6 +42,7 @@ const BATTLE_PATHS = new Set([
 
 function createPoiTelemetry(options = {}) {
   const now = options.now || (() => new Date())
+  const actionEvents = createPoiActionEvents({ now })
   let questGeneration = 0
   let questList = null
   let questActionGeneration = 0
@@ -54,21 +57,22 @@ function createPoiTelemetry(options = {}) {
   function handleGameResponse(event) {
     const detail = event && event.detail
     if (!detail || typeof detail.path !== 'string') return
+    const actionEvent = actionEvents.capture(detail)
 
     if (detail.path === QUEST_LIST_PATH) {
-      captureQuestList(detail)
+      captureQuestList(detail, actionEvent)
       return
     }
     if (QUEST_ACTION_PATHS.has(detail.path)) {
-      captureQuestAction(detail)
+      captureQuestAction(detail, actionEvent)
       return
     }
     if (EQUIPMENT_ACTION_PATHS.has(detail.path)) {
-      captureEquipmentAction(detail)
+      captureEquipmentAction(detail, actionEvent)
       return
     }
     if (detail.path === FLEET_ACTION_PATH) {
-      captureFleetAction(detail)
+      captureFleetAction(detail, actionEvent)
       return
     }
     if (BATTLE_RESULT_PATHS.has(detail.path)) {
@@ -80,7 +84,7 @@ function createPoiTelemetry(options = {}) {
     }
   }
 
-  function captureQuestList(detail) {
+  function captureQuestList(detail, actionEvent) {
     const body = detail.body
     const postBody = detail.postBody
     const tabId = toInteger(postBody && postBody.api_tab_id)
@@ -105,7 +109,9 @@ function createPoiTelemetry(options = {}) {
     questList = {
       available: true,
       generation: questGeneration,
-      capturedAt: now().toISOString(),
+      capturedAt: actionEvent
+        ? actionEvent.capturedAt
+        : now().toISOString(),
       tabId,
       pageNo: nonNegativeInteger(body.api_disp_page),
       pageCount: nonNegativeInteger(body.api_page_count),
@@ -116,7 +122,11 @@ function createPoiTelemetry(options = {}) {
     }
   }
 
-  function captureQuestAction(detail) {
+  function captureQuestAction(detail, actionEvent) {
+    const apiResult = actionEvent
+      ? actionEvent.apiResult
+      : equipmentApiResult(detail)
+    if (apiResult !== 1) return
     const postBody = detail.postBody
     const questId = toInteger(postBody && postBody.api_quest_id)
     if (questId == null || questId <= 0) return
@@ -125,15 +135,20 @@ function createPoiTelemetry(options = {}) {
     questAction = {
       available: true,
       generation: questActionGeneration,
-      capturedAt: now().toISOString(),
-      path: detail.path,
+      capturedAt: actionEvent
+        ? actionEvent.capturedAt
+        : now().toISOString(),
+      path: actionEvent ? actionEvent.path : detail.path,
       questId,
       flag: toInteger(postBody && postBody.api_quest_flag),
+      apiResult,
     }
   }
 
-  function captureEquipmentAction(detail) {
-    const apiResult = equipmentApiResult(detail)
+  function captureEquipmentAction(detail, actionEvent) {
+    const apiResult = actionEvent
+      ? actionEvent.apiResult
+      : equipmentApiResult(detail)
     if (apiResult === 0) return
     const postBody = normalizeEquipmentPostBody(detail.path, detail.postBody)
     if (!postBody) return
@@ -142,15 +157,19 @@ function createPoiTelemetry(options = {}) {
     equipmentAction = {
       available: true,
       generation: equipmentActionGeneration,
-      capturedAt: now().toISOString(),
-      path: detail.path,
+      capturedAt: actionEvent
+        ? actionEvent.capturedAt
+        : now().toISOString(),
+      path: actionEvent ? actionEvent.path : detail.path,
       apiResult,
       postBody,
     }
   }
 
-  function captureFleetAction(detail) {
-    const apiResult = equipmentApiResult(detail)
+  function captureFleetAction(detail, actionEvent) {
+    const apiResult = actionEvent
+      ? actionEvent.apiResult
+      : equipmentApiResult(detail)
     if (apiResult === 0) return
     const postBody = normalizeFleetPostBody(detail.postBody)
     if (!postBody) return
@@ -159,8 +178,10 @@ function createPoiTelemetry(options = {}) {
     fleetAction = {
       available: true,
       generation: fleetActionGeneration,
-      capturedAt: now().toISOString(),
-      path: detail.path,
+      capturedAt: actionEvent
+        ? actionEvent.capturedAt
+        : now().toISOString(),
+      path: actionEvent ? actionEvent.path : detail.path,
       apiResult,
       postBody,
     }
@@ -234,6 +255,9 @@ function createPoiTelemetry(options = {}) {
     getFleetAction() {
       return fleetAction || { available: false, generation: 0 }
     },
+    getActionEvents(options) {
+      return actionEvents.read(options)
+    },
     getBattleTelemetry() {
       return battleTelemetry || { available: false, generation: 0 }
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "poi-plugin-mcp",
-  "version": "0.2.12",
+  "version": "0.2.13",
   "description": "Poi data, WebView capture, and opt-in authenticated input bridge for local KanColle tools.",
   "main": "index.js",
   "keywords": [