summer-engine 3.6.0 → 3.8.0

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

@@ -0,0 +1,67 @@
+id: tool/app-create
+kind: tool
+version: 1.0.0
+summary: Create a new scratch Summer App (a tool for the person's team inside Summer Studio) and open it in their Studio tab.
+use_when:
+  - '"build me a tool for…" / "make an app that…"'
+  - the person needs a UI to decide or edit something they will come back to
+do_not_use_when:
+  - "a one-off answer: reply in chat"
+facets:
+  lifecycle:
+    - build
+  domains:
+    - tools
+    - ui
+compatibility:
+  engine: ">=4.6"
+related:
+  skills:
+    - skill/summer-apps
+source: official
+license: MIT
+status: preview
+aliases:
+  - summer_app_create
+implementation:
+  module: src/mcp/tools/app-tools.ts
+  export: registerAppTools
+surfaces:
+  mcp:
+    tool_name: summer_app_create
+    remote: true
+input_schema:
+  type: object
+  properties:
+    name:
+      type: string
+      minLength: 1
+      maxLength: 80
+    purpose:
+      type: string
+      maxLength: 280
+      description: "One line: what the tool does and where its data goes"
+    format:
+      type: string
+      enum:
+        - code
+        - layout
+      default: code
+      description: "code: index.html + JS/CSS (default). layout: a JSON layout of kit nodes, for quick decision UIs"
+    workspaceId:
+      type: string
+      format: uuid
+      description: "A workspace id. Default: the person's team (the one their Studio tab is on, else their latest team, else personal); the result's workspace says which"
+    folder:
+      type: string
+      minLength: 1
+      maxLength: 80
+  required:
+    - name
+  additionalProperties: false
+authority:
+  filesystem: false
+  editor_mutation: false
+  network: true
+  credentials: false
+  publish: false

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

@@ -0,0 +1,74 @@
+id: tool/app-data
+kind: tool
+version: 1.0.0
+summary: Read or write a Summer App's shared data collections; works with no app open and the team sees writes live.
+use_when:
+  - '"nerf the bow in our balance sheet"'
+  - seeding an app with data
+  - reading what the team entered in an app
+facets:
+  lifecycle:
+    - build
+  domains:
+    - tools
+    - ui
+compatibility:
+  engine: ">=4.6"
+related:
+  skills:
+    - skill/summer-apps
+source: official
+license: MIT
+status: preview
+aliases:
+  - summer_app_data
+implementation:
+  module: src/mcp/tools/app-tools.ts
+  export: registerAppTools
+surfaces:
+  mcp:
+    tool_name: summer_app_data
+    remote: true
+input_schema:
+  type: object
+  properties:
+    appId:
+      type: string
+      format: uuid
+      description: The app id from summer_app_create or summer_app_list
+    collection:
+      type: string
+      maxLength: 48
+      description: "Read: one collection. Default: all"
+    after:
+      type: string
+      maxLength: 200
+      description: "Read: the next cursor from the previous page"
+    limit:
+      type: integer
+      minimum: 1
+      maximum: 500
+      default: 200
+    ops:
+      type: array
+      items:
+        type: object
+        additionalProperties: {}
+      minItems: 1
+      maxItems: 100
+      description: "Write: [{op: put, collection, recordId, data}, {op: patch, collection, recordId, patch}, {op: remove, collection, recordId}]; ifRevision on an op applies it only at that record revision (0: must not exist)"
+    as:
+      type: string
+      enum:
+        - agent
+        - seed
+      description: "Write: seed for starter data that belongs to the team (no author). Default: agent"
+  required:
+    - appId
+  additionalProperties: false
+authority:
+  filesystem: false
+  editor_mutation: false
+  network: true
+  credentials: false
+  publish: false

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

@@ -0,0 +1,59 @@
+id: tool/app-dock
+kind: tool
+version: 1.0.0
+summary: Dock a Summer App as a panel in the running Summer Engine editor, close it, or list docked apps.
+use_when:
+  - '"put the quest editor next to my scene"'
+  - keeping a team tool open while editing
+facets:
+  lifecycle:
+    - build
+  domains:
+    - tools
+    - ui
+compatibility:
+  engine: ">=4.6"
+related:
+  skills:
+    - skill/summer-apps
+source: official
+license: MIT
+status: preview
+aliases:
+  - summer_app_dock
+implementation:
+  module: src/mcp/tools/app-tools.ts
+  export: registerAppTools
+surfaces:
+  mcp:
+    tool_name: summer_app_dock
+    remote: false
+input_schema:
+  type: object
+  properties:
+    action:
+      type: string
+      enum:
+        - open
+        - close
+        - list
+      default: open
+    appId:
+      type: string
+      format: uuid
+      description: "open, close: the app"
+    slot:
+      type: string
+      enum:
+        - left
+        - right
+        - bottom
+      default: right
+      description: "open: left, right or bottom"
+  additionalProperties: false
+authority:
+  filesystem: false
+  editor_mutation: true
+  network: false
+  credentials: false
+  publish: false

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