summer-engine 3.7.0 → 3.8.0

package/library/tools/app-events/resource.yaml

@@ -0,0 +1,68 @@
+id: tool/app-events
+kind: tool
+version: 1.0.0
+summary: "Wait for what a Summer App sends to agents: summer.agent.send events, app errors, feedback and tool calls."
+use_when:
+  - waiting for the person to act in an app you built
+  - checking an app for errors after publishing
+facets:
+  lifecycle:
+    - build
+  domains:
+    - tools
+    - ui
+compatibility:
+  engine: ">=4.6"
+related:
+  skills:
+    - skill/summer-apps
+source: official
+license: MIT
+status: preview
+aliases:
+  - summer_app_events
+implementation:
+  module: src/mcp/tools/app-tools.ts
+  export: registerAppTools
+surfaces:
+  mcp:
+    tool_name: summer_app_events
+    remote: true
+input_schema:
+  type: object
+  properties:
+    appId:
+      type: string
+      format: uuid
+      description: The app id from summer_app_create or summer_app_list
+    after:
+      type: integer
+      minimum: 0
+      default: 0
+      description: "Return events after this cursor (0: from the start). Pass the returned cursor next time"
+    timeoutSeconds:
+      type: integer
+      minimum: 0
+      maximum: 50
+      default: 25
+      description: Wait up to this long (max 50) for the first new event
+    kinds:
+      type: array
+      items:
+        type: string
+        enum:
+          - agent
+          - error
+          - feedback
+          - tool
+      maxItems: 4
+      description: "Default: agent, error, feedback"
+  required:
+    - appId
+  additionalProperties: false
+authority:
+  filesystem: false
+  editor_mutation: false
+  network: true
+  credentials: false
+  publish: false

package/library/tools/app-get/resource.yaml

@@ -0,0 +1,46 @@
+id: tool/app-get
+kind: tool
+version: 1.0.0
+summary: Read a Summer App's manifest, current files (or layout) and shared data summary.
+use_when:
+  - before changing an existing app
+  - '"what does our loot table app do"'
+facets:
+  lifecycle:
+    - build
+  domains:
+    - tools
+    - ui
+compatibility:
+  engine: ">=4.6"
+related:
+  skills:
+    - skill/summer-apps
+source: official
+license: MIT
+status: preview
+aliases:
+  - summer_app_get
+implementation:
+  module: src/mcp/tools/app-tools.ts
+  export: registerAppTools
+surfaces:
+  mcp:
+    tool_name: summer_app_get
+    remote: true
+input_schema:
+  type: object
+  properties:
+    appId:
+      type: string
+      format: uuid
+      description: The app id from summer_app_create or summer_app_list
+  required:
+    - appId
+  additionalProperties: false
+authority:
+  filesystem: false
+  editor_mutation: false
+  network: true
+  credentials: false
+  publish: false

package/library/tools/app-guide/resource.yaml

@@ -0,0 +1,55 @@
+id: tool/app-guide
+kind: tool
+version: 1.0.0
+summary: "Read the Summer Apps build guide: when to build an app, Layout vs code, build loop, manifest, SDK, UI kit, layout format, design rules and worked examples."
+use_when:
+  - before building or changing a Summer App
+  - '"build us a loot balance tool"'
+  - '"make a tool for our team to track creatures"'
+facets:
+  lifecycle:
+    - build
+  domains:
+    - tools
+    - ui
+compatibility:
+  engine: ">=4.6"
+related:
+  skills:
+    - skill/summer-apps
+source: official
+license: MIT
+status: preview
+aliases:
+  - summer_app_guide
+implementation:
+  module: src/mcp/tools/app-tools.ts
+  export: registerAppTools
+surfaces:
+  mcp:
+    tool_name: summer_app_guide
+    remote: true
+input_schema:
+  type: object
+  properties:
+    section:
+      type: string
+      enum:
+        - all
+        - overview
+        - manifest
+        - sdk
+        - kit
+        - layout
+        - design
+        - examples
+        - types
+      default: all
+      description: "One part of the guide: overview, manifest, sdk, kit, layout, design, examples, or types (the SDK's exact TypeScript types, not in all). Default all"
+  additionalProperties: false
+authority:
+  filesystem: false
+  editor_mutation: false
+  network: true
+  credentials: false
+  publish: false

package/library/tools/app-list/resource.yaml

@@ -0,0 +1,48 @@
+id: tool/app-list
+kind: tool
+version: 1.0.0
+summary: List the Summer Apps (team tools inside Summer Studio) in the person's workspaces.
+use_when:
+  - '"which apps do we have"'
+  - finding an app id to change or read
+facets:
+  lifecycle:
+    - build
+  domains:
+    - tools
+    - ui
+compatibility:
+  engine: ">=4.6"
+related:
+  skills:
+    - skill/summer-apps
+source: official
+license: MIT
+status: preview
+aliases:
+  - summer_app_list
+implementation:
+  module: src/mcp/tools/app-tools.ts
+  export: registerAppTools
+surfaces:
+  mcp:
+    tool_name: summer_app_list
+    remote: true
+input_schema:
+  type: object
+  properties:
+    workspaceId:
+      type: string
+      format: uuid
+      description: "Only this workspace (team). Default: every workspace the person is in"
+    q:
+      type: string
+      maxLength: 200
+      description: Search app names and purposes
+  additionalProperties: false
+authority:
+  filesystem: false
+  editor_mutation: false
+  network: true
+  credentials: false
+  publish: false

package/library/tools/app-page/resource.yaml

@@ -0,0 +1,74 @@
+id: tool/app-page
+kind: tool
+version: 1.0.0
+summary: Read or use the fields and buttons an open Summer App declared (fill values, press actions).
+use_when:
+  - '"set the budget to 60 in the balance app"'
+  - reading what the person has selected in an open app
+do_not_use_when:
+  - "changing shared data with no app open: summer_app_data"
+facets:
+  lifecycle:
+    - build
+  domains:
+    - tools
+    - ui
+compatibility:
+  engine: ">=4.6"
+related:
+  skills:
+    - skill/summer-apps
+source: official
+license: MIT
+status: preview
+aliases:
+  - summer_app_page
+implementation:
+  module: src/mcp/tools/app-tools.ts
+  export: registerAppTools
+surfaces:
+  mcp:
+    tool_name: summer_app_page
+    remote: true
+input_schema:
+  type: object
+  properties:
+    appId:
+      type: string
+      format: uuid
+      description: The app id from summer_app_create or summer_app_list
+    fill:
+      type: array
+      items:
+        type: object
+        properties:
+          field:
+            type: string
+            minLength: 1
+            maxLength: 200
+          value:
+            anyOf:
+              - type: string
+                maxLength: 10000
+              - type: number
+              - type: boolean
+        required:
+          - field
+          - value
+        additionalProperties: false
+      maxItems: 50
+      description: "Values to set: [{field, value}] with field ids from a read"
+    press:
+      type: string
+      minLength: 1
+      maxLength: 200
+      description: An action id to press after filling
+  required:
+    - appId
+  additionalProperties: false
+authority:
+  filesystem: false
+  editor_mutation: false
+  network: true
+  credentials: false
+  publish: false

package/library/tools/app-publish/resource.yaml

@@ -0,0 +1,90 @@
+id: tool/app-publish
+kind: tool
+version: 1.0.0
+summary: Publish a new version of a Summer App from a local folder, files or a layout; the person's Studio tab boots it.
+use_when:
+  - after writing or changing an app's files
+  - fixing an app after a publish error or an app error event
+facets:
+  lifecycle:
+    - build
+  domains:
+    - tools
+    - ui
+compatibility:
+  engine: ">=4.6"
+related:
+  skills:
+    - skill/summer-apps
+source: official
+license: MIT
+status: preview
+aliases:
+  - summer_app_publish
+implementation:
+  module: src/mcp/tools/app-tools.ts
+  export: registerAppTools
+surfaces:
+  mcp:
+    tool_name: summer_app_publish
+    remote: true
+input_schema:
+  type: object
+  properties:
+    appId:
+      type: string
+      format: uuid
+      description: The app id from summer_app_create or summer_app_list
+    dir:
+      type: string
+      minLength: 1
+      description: A local folder holding the app (index.html at its root). Every file under it is published; dotfiles and node_modules are skipped
+    files:
+      type: array
+      items:
+        type: object
+        properties:
+          path:
+            type: string
+            minLength: 1
+            maxLength: 200
+          content:
+            type: string
+          encoding:
+            type: string
+            enum:
+              - utf8
+              - base64
+            default: utf8
+        required:
+          - path
+          - content
+        additionalProperties: false
+      maxItems: 300
+      description: "The files instead of dir: [{path, content, encoding}]"
+    layout:
+      type: object
+      additionalProperties: {}
+      description: "Layout apps: { version: 1, title, root }"
+    manifest:
+      type: object
+      additionalProperties: {}
+      description: The manifest {name, purpose, permissions, engineFiles, agentEvents, agentTools} (summer_app_guide section manifest)
+    note:
+      type: string
+      maxLength: 500
+      description: What changed, shown in the version list
+    idempotencyKey:
+      type: string
+      minLength: 8
+      maxLength: 128
+  required:
+    - appId
+    - manifest
+  additionalProperties: false
+authority:
+  filesystem: true
+  editor_mutation: false
+  network: true
+  credentials: false
+  publish: false

package/library/tools/app-report-gap/resource.yaml

@@ -0,0 +1,58 @@
+id: tool/app-report-gap
+kind: tool
+version: 1.0.0
+summary: Report an SDK capability a Summer App needed and did not have, so Summer builds it.
+use_when:
+  - an app needed to reach a service or engine feature the SDK does not offer
+  - an app needs something the Summer Apps SDK cannot do
+facets:
+  lifecycle:
+    - build
+  domains:
+    - tools
+    - ui
+compatibility:
+  engine: ">=4.6"
+related:
+  skills:
+    - skill/summer-apps
+source: official
+license: MIT
+status: preview
+aliases:
+  - summer_app_report_gap
+implementation:
+  module: src/mcp/tools/app-tools.ts
+  export: registerAppTools
+surfaces:
+  mcp:
+    tool_name: summer_app_report_gap
+    remote: true
+input_schema:
+  type: object
+  properties:
+    capability:
+      type: string
+      minLength: 1
+      maxLength: 200
+      description: What the app needed, e.g. "read Steam reviews"
+    detail:
+      type: string
+      maxLength: 2000
+    method:
+      type: string
+      maxLength: 100
+      description: The SDK method name you wished existed
+    appId:
+      type: string
+      format: uuid
+      description: The app id from summer_app_create or summer_app_list
+  required:
+    - capability
+  additionalProperties: false
+authority:
+  filesystem: false
+  editor_mutation: false
+  network: true
+  credentials: false
+  publish: false

package/library/tools/app-screenshot/resource.yaml

@@ -0,0 +1,85 @@
+id: tool/app-screenshot
+kind: tool
+version: 1.0.0
+summary: See a Summer App without the person - a headless, read-only render (PNG) with its console, errors, refused calls and declared page.
+use_when:
+  - right after every summer_app_publish, to check the app renders with real data
+  - '"does my app look right on a phone / in dark mode"'
+  - finding why an app shows nothing (SDK not connected, script errors)
+do_not_use_when:
+  - "testing writes, sends or paid calls: they are refused in screenshots; they work in Studio"
+facets:
+  lifecycle:
+    - build
+  domains:
+    - tools
+    - ui
+compatibility:
+  engine: ">=4.6"
+related:
+  skills:
+    - skill/summer-apps
+    - skill/summer-apps-design
+source: official
+license: MIT
+status: preview
+aliases:
+  - summer_app_screenshot
+implementation:
+  module: src/mcp/tools/app-tools.ts
+  export: registerAppTools
+surfaces:
+  mcp:
+    tool_name: summer_app_screenshot
+    remote: true
+input_schema:
+  type: object
+  properties:
+    appId:
+      type: string
+      format: uuid
+      description: The app id from summer_app_create or summer_app_list
+    version:
+      type: integer
+      exclusiveMinimum: 0
+      description: "A published version. Default: the current one"
+    width:
+      type: integer
+      minimum: 320
+      maximum: 1920
+      default: 1280
+      description: "Viewport width in px: 390 for a phone"
+    height:
+      type: integer
+      minimum: 320
+      maximum: 1600
+      default: 800
+    theme:
+      type: string
+      enum:
+        - light
+        - dark
+      default: light
+    fullPage:
+      type: boolean
+      default: false
+      description: Capture the whole scroll height (up to 4000 px)
+    params:
+      type: object
+      additionalProperties:
+        type: string
+        maxLength: 500
+      description: Launch params, as in /studio/apps/<id>?key=value
+    out:
+      type: string
+      minLength: 1
+      description: Also save the PNG to this local path
+  required:
+    - appId
+  additionalProperties: false
+authority:
+  filesystem: true
+  editor_mutation: false
+  network: true
+  credentials: false
+  publish: false

package/library/tools/app-tools/resource.yaml

@@ -0,0 +1,46 @@
+id: tool/app-tools
+kind: tool
+version: 1.0.0
+summary: List the agent tools a Summer App declares.
+use_when:
+  - before calling app logic with summer_app_call
+  - '"what can our balance app do for me"'
+facets:
+  lifecycle:
+    - build
+  domains:
+    - tools
+    - ui
+compatibility:
+  engine: ">=4.6"
+related:
+  skills:
+    - skill/summer-apps
+source: official
+license: MIT
+status: preview
+aliases:
+  - summer_app_tools
+implementation:
+  module: src/mcp/tools/app-tools.ts
+  export: registerAppTools
+surfaces:
+  mcp:
+    tool_name: summer_app_tools
+    remote: true
+input_schema:
+  type: object
+  properties:
+    appId:
+      type: string
+      format: uuid
+      description: The app id from summer_app_create or summer_app_list
+  required:
+    - appId
+  additionalProperties: false
+authority:
+  filesystem: false
+  editor_mutation: false
+  network: true
+  credentials: false
+  publish: false

package/library/tools/app-update/resource.yaml

@@ -0,0 +1,68 @@
+id: tool/app-update
+kind: tool
+version: 1.0.0
+summary: Rename a Summer App, move it to a folder, or keep, archive or restore it.
+use_when:
+  - archiving a scratch app you made that the person did not keep
+  - '"rename the loot app to Drop tables"'
+  - '"keep this app" (status kept)'
+facets:
+  lifecycle:
+    - build
+  domains:
+    - tools
+    - ui
+compatibility:
+  engine: ">=4.6"
+related:
+  skills:
+    - skill/summer-apps
+source: official
+license: MIT
+status: preview
+aliases:
+  - summer_app_update
+implementation:
+  module: src/mcp/tools/app-tools.ts
+  export: registerAppTools
+surfaces:
+  mcp:
+    tool_name: summer_app_update
+    remote: true
+input_schema:
+  type: object
+  properties:
+    appId:
+      type: string
+      format: uuid
+      description: The app id from summer_app_create or summer_app_list
+    name:
+      type: string
+      minLength: 1
+      maxLength: 80
+    purpose:
+      type: string
+      maxLength: 280
+    status:
+      type: string
+      enum:
+        - scratch
+        - kept
+        - archived
+      description: "kept: the team keeps it. archived: hidden from the app list (restore with scratch or kept)"
+    folder:
+      type:
+        - string
+        - "null"
+      minLength: 1
+      maxLength: 80
+      description: null takes it out of its folder
+  required:
+    - appId
+  additionalProperties: false
+authority:
+  filesystem: false
+  editor_mutation: false
+  network: true
+  credentials: false
+  publish: false

package/library/tools/enable-plugin/resource.yaml

@@ -0,0 +1,53 @@
+id: tool/enable-plugin
+kind: tool
+version: 1.0.0
+summary: Enable an editor plugin (res://addons/<name>/) and report the real load result, or that an older engine only queued it.
+use_when:
+  - an agent wrote or installed an editor plugin and needs it running
+  - a Summer App's paired plugin must be enabled before the app can message it
+  - '"turn on the quest_tools plugin"'
+facets:
+  lifecycle:
+    - build
+  domains:
+    - editor
+    - tools
+compatibility:
+  engine: ">=4.6"
+related:
+  skills:
+    - skill/summer-apps
+source: official
+license: MIT
+status: preview
+aliases:
+  - summer_enable_plugin
+implementation:
+  module: src/mcp/tools/app-tools.ts
+  export: registerAppTools
+surfaces:
+  mcp:
+    tool_name: summer_enable_plugin
+    remote: false
+input_schema:
+  type: object
+  properties:
+    plugin:
+      type: string
+      minLength: 1
+      maxLength: 200
+      description: The plugin folder under res://addons/ (e.g. 'quest_tools') or its 'res://addons/<name>/plugin.cfg'
+    timeoutMs:
+      type: integer
+      minimum: 1000
+      maximum: 120000
+      description: How long the engine waits for the plugin to load (default 30000)
+  required:
+    - plugin
+  additionalProperties: false
+authority:
+  filesystem: false
+  editor_mutation: true
+  network: false
+  credentials: false
+  publish: false

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "summer-engine",
-  "version": "3.7.0",
+  "version": "3.8.0",
   "description": "Local Summer CLI and MCP server for Summer Engine. Install and run the engine, connect Claude Code, Cursor, Codex, Gemini, and other agents, and build real games with bundled skills, hooks, and plugins.",
   "keywords": [
     "summer-engine",