@malloy-publisher/server 0.9.8 → 0.9.9

package/dist/app/api-doc.yaml

@@ -78,6 +78,15 @@ tags:
     description:
       In-package HTML data apps (static pages served from a package's public/
       directory)
+  - name: skills
+    description:
+      Agent skills in force for a package - the bundled guides plus the package's
+      own `skills/`, with the package's copy replacing a bundled one of the same
+      name
+  - name: agents
+    description:
+      Agents a package declares in `publisher.json`, resolved to their
+      instructions, skill files and schedules (served, never run)
   - name: databases
     description: Embedded database management and access
   - name: watch-mode
@@ -2170,6 +2179,288 @@ paths:
         "503":
           $ref: "#/components/responses/ServiceUnavailable"
 
+  /environments/{environmentName}/packages/{packageName}/skills:
+    get:
+      tags:
+        - skills
+      operationId: list-skills
+      summary: List the agent skills in force for a package
+      description: |
+        Lists the agent skills that apply to this package: the guides bundled
+        with this server, plus any the package ships under `skills/`.
+
+        Resolution is name shadowing. A package skill whose `name` matches a
+        bundled skill REPLACES it for this package; one with a new name is
+        added. Nothing is merged, because the server does not know which guides
+        the calling agent already holds and so cannot patch one. Read `origin`
+        on each entry to tell a replaced skill from the original.
+
+        Bodies are not returned here. Fetch one with
+        `GET .../skills/{skillName}`. An entry whose `name` contains a slash
+        (`<skill>/<stem>`) is a skill's on-demand reference file, addressed by
+        the pointer at the end of its parent's body.
+
+        The REST half of the `get_skill` MCP tool, for callers running
+        unattended.
+      parameters:
+        - name: environmentName
+          in: path
+          description: Name of the environment
+          required: true
+          schema:
+            $ref: "#/components/schemas/IdentifierPattern"
+        - name: packageName
+          in: path
+          description: Name of the package
+          required: true
+          schema:
+            $ref: "#/components/schemas/IdentifierPattern"
+      responses:
+        "200":
+          description: The skills in force for the package
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/SkillSummary"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "500":
+          $ref: "#/components/responses/InternalServerError"
+        "503":
+          $ref: "#/components/responses/ServiceUnavailable"
+
+  /environments/{environmentName}/packages/{packageName}/skills/{skillName}:
+    get:
+      tags:
+        - skills
+      operationId: get-skill
+      summary: Get one agent skill, with its body
+      description: |
+        Returns one skill in force for this package, including its full
+        Markdown. `skillName` is a name from the listing, exactly as spelled
+        there; a reference file is addressed as `<skill>/<stem>`. The slash may
+        be sent literally or as `%2F`; a literal `%` in a name must be sent as
+        `%25`.
+
+        404 when no skill of that name is in force.
+      parameters:
+        - name: environmentName
+          in: path
+          description: Name of the environment
+          required: true
+          schema:
+            $ref: "#/components/schemas/IdentifierPattern"
+        - name: packageName
+          in: path
+          description: Name of the package
+          required: true
+          schema:
+            $ref: "#/components/schemas/IdentifierPattern"
+        - name: skillName
+          in: path
+          description: >-
+            Skill name as returned by the listing. A reference file is
+            `<skill>/<stem>`; the slash may be literal or `%2F`.
+          required: true
+          schema:
+            type: string
+      responses:
+        "200":
+          description: The skill and its body
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Skill"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "500":
+          $ref: "#/components/responses/InternalServerError"
+        "503":
+          $ref: "#/components/responses/ServiceUnavailable"
+
+  /environments/{environmentName}/packages/{packageName}/agents:
+    get:
+      tags:
+        - agents
+      operationId: list-agents
+      summary: List the agents a package declares
+      description: |
+        Lists the agents declared under `agents` in the package's
+        `publisher.json` that passed validation, without instructions or
+        skills. An agent that failed validation is not listed; the package's
+        `warnings` say why. Empty when the manifest declares none.
+
+        The REST half of the `get_agent` MCP tool.
+      parameters:
+        - name: environmentName
+          in: path
+          description: Name of the environment
+          required: true
+          schema:
+            $ref: "#/components/schemas/IdentifierPattern"
+        - name: packageName
+          in: path
+          description: Name of the package
+          required: true
+          schema:
+            $ref: "#/components/schemas/IdentifierPattern"
+      responses:
+        "200":
+          description: The agents the package declares
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/AgentSummary"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "500":
+          $ref: "#/components/responses/InternalServerError"
+        "503":
+          $ref: "#/components/responses/ServiceUnavailable"
+
+  /environments/{environmentName}/packages/{packageName}/agents/{agentName}:
+    get:
+      tags:
+        - agents
+      operationId: get-agent
+      summary: Get one agent, resolved
+      description: |
+        Returns one agent with its instructions, its own skill files and each
+        schedule's task text, plus `source`, which pins the package load and the
+        agent's own content so a runner can prove which bytes ran. Publisher
+        serves the definition and runs nothing: the caller's own harness
+        executes it, and schedules are never fired by the server.
+
+        404 when no agent of that name is served.
+      parameters:
+        - name: environmentName
+          in: path
+          description: Name of the environment
+          required: true
+          schema:
+            $ref: "#/components/schemas/IdentifierPattern"
+        - name: packageName
+          in: path
+          description: Name of the package
+          required: true
+          schema:
+            $ref: "#/components/schemas/IdentifierPattern"
+        - name: agentName
+          in: path
+          description: >-
+            Agent name as returned by the listing. Names are 1-64 lowercase
+            letters, digits and single hyphens; any other value is a 404, not a
+            400.
+          required: true
+          schema:
+            type: string
+            pattern: "^[a-z0-9]+(-[a-z0-9]+)*$"
+            maxLength: 64
+        - name: skills
+          in: query
+          description: >-
+            `full` (the default) returns every skill file with its text.
+            `summary` returns each file's `relative_filepath` and `bytes`, plus
+            `name` and `description` for a `SKILL.md`, and no `file_contents`;
+            fetch a file with `GET .../agents/{agentName}/skills/{path}`. The
+            `source` pin is identical in both. Any other value, including an
+            empty one, is a 400.
+          required: false
+          schema:
+            type: string
+            enum: [full, summary]
+            default: full
+      responses:
+        "200":
+          description: The resolved agent
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Agent"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "500":
+          $ref: "#/components/responses/InternalServerError"
+        "503":
+          $ref: "#/components/responses/ServiceUnavailable"
+
+  /environments/{environmentName}/packages/{packageName}/agents/{agentName}/skills/{relativeFilepath}:
+    get:
+      tags:
+        - agents
+      operationId: get-agent-skill-file
+      summary: Get one of an agent's skill files
+      description: |
+        Returns one file from the agent's resolved skill set, named by a
+        `relative_filepath` from `GET .../agents/{agentName}?skills=summary`
+        (for example `analyst-conventions/SKILL.md`), with the same `source`
+        pin as the full definition. The path is looked up in the resolved set,
+        never joined onto the filesystem.
+
+        404 when the agent or the file is not served.
+      parameters:
+        - name: environmentName
+          in: path
+          description: Name of the environment
+          required: true
+          schema:
+            $ref: "#/components/schemas/IdentifierPattern"
+        - name: packageName
+          in: path
+          description: Name of the package
+          required: true
+          schema:
+            $ref: "#/components/schemas/IdentifierPattern"
+        - name: agentName
+          in: path
+          description: >-
+            Agent name as returned by the listing. Names are 1-64 lowercase
+            letters, digits and single hyphens; any other value is a 404, not a
+            400.
+          required: true
+          schema:
+            type: string
+            pattern: "^[a-z0-9]+(-[a-z0-9]+)*$"
+            maxLength: 64
+        - name: relativeFilepath
+          in: path
+          description: >-
+            A `relative_filepath` from the agent's skill summary. Slashes may be
+            sent literally or as `%2F`; a literal `%` in a name must be sent as
+            `%25`.
+          required: true
+          schema:
+            type: string
+      responses:
+        "200":
+          description: The skill file
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AgentSkillRead"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "500":
+          $ref: "#/components/responses/InternalServerError"
+        "503":
+          $ref: "#/components/responses/ServiceUnavailable"
+
   # ── DEPRECATED ──────────────────────────────────────────────────────────
   # The `…/dashboards*` and `…/notebooks*` routes, kept for clients that still
   # read them, until a later release removes them. Use `…/reports*` above.
@@ -3686,6 +3977,14 @@ components:
             `grid` or `linear`). The rest are `warn` (a mistyped `(markdown)`
             opener, `report-layout-implicit` for a tag that names no layout and lists
             no tiles, a block that never closes, and similar).
+            Skill and agent findings, all `warn`: a package skill under
+            `skills/` that is not served (unreadable or linked-out `SKILL.md`,
+            a frontmatter `name` that is not its directory name, a `skills/`
+            directory that links out of the package) or served with a gap (no
+            `description`, a `reference/` that cannot be listed or read); and
+            each agent the manifest declares that is not served, or is served
+            with a finding (an agent skill with no `description`, a skills
+            directory with no skills, an unreadable reference).
             Deprecated-format findings, all `warn`: each `.malloynb` notebook
             (`model` is its path), and each source a file declares deprecated
             `#(filter)` annotations on (`model` is that file, `subject` the
@@ -4128,6 +4427,238 @@ components:
             discovery index, which is what `get_context` ranks against
             when an embedding provider is configured. `status: lexical` when
             the server has no provider, because there is no index to describe.
+        servedRevision:
+          type: string
+          readOnly: true
+          description: >-
+            Server-computed, read-only: an identifier for the load that produced
+            what this package is currently serving. Minted fresh per load, so
+            two loads of byte-identical files carry different revisions. Use it
+            to tell one load from another, NOT to tell whether content changed:
+            it moves on every reload regardless. `sourceContentSha` answers that.
+        sourceContentSha:
+          type: string
+          readOnly: true
+          description: >-
+            Server-computed, read-only: SHA-256 over the package-relative path
+            and bytes of every file the package is serving: each model file,
+            each package skill file under `skills/`, and, when the manifest
+            declares `agents`, the canonical form of that `agents` object plus
+            every instructions, task and skill file those agents read.
+
+            This is the reload receipt. Publisher serves a COPY of a package
+            under `publisher_data/<env>/<pkg>/` unless the environment was
+            started with `--watch-env`, so an edit to the original source
+            directory reaches nothing and the reload still reports success.
+            Comparing this value across a reload is what distinguishes "the
+            server recompiled my edit" from "the server recompiled the same
+            bytes it already had".
+
+            It covers EVERY model path in the package, so an edit to an imported
+            file moves it where a hash of one model path would not. It covers
+            nothing outside the list above: a data file, a `public/` asset, a
+            `version` bump or any other key in publisher.json (`retrieval`,
+            `explores`, `queryableSources`, `scope`) all leave it unchanged,
+            although some of those do change what is served. An unchanged value
+            therefore proves an edit to a hashed file did not reach the served
+            copy, and says nothing about an edit to anything else.
+        agents:
+          type: array
+          readOnly: true
+          description: >-
+            Server-computed, read-only: the agents this package's
+            `publisher.json` declares and the server accepted, without their
+            instructions. Absent when the manifest declares no `agents`. An
+            agent that failed validation is left out and named in `warnings`.
+            Fetch one with `GET .../agents/{agentName}`.
+          items:
+            $ref: "#/components/schemas/AgentSummary"
+
+    AgentSchedule:
+      type: object
+      readOnly: true
+      description: >-
+        A cron schedule an agent declares. Validated and exposed only: the
+        server never runs it.
+      properties:
+        cron:
+          type: string
+          description: A 5-field UNIX cron expression, evaluated in UTC.
+        task:
+          type: string
+          description: Package-relative path of the task file, as written in the manifest.
+        taskContent:
+          type: string
+          description: >-
+            The task file's Markdown. Only on the resolved agent, not the
+            listing.
+
+    AgentSummary:
+      type: object
+      readOnly: true
+      description: One agent a package declares, without its instructions or skills.
+      properties:
+        name:
+          type: string
+          description: The agent's name (its key in the manifest's `agents` object).
+        description:
+          type: string
+        model:
+          type: string
+          description: The model the agent asks for; `inherit` when the manifest sets none.
+        schedules:
+          type: array
+          items:
+            $ref: "#/components/schemas/AgentSchedule"
+
+    AgentSkillFile:
+      type: object
+      readOnly: true
+      description: >-
+        One of an agent's skill files. The snake_case keys
+        (`relative_filepath`, `file_contents`) mirror the MCP `get_agent` tool
+        the shape is shared with, unlike the camelCase used elsewhere in this
+        API.
+      properties:
+        relative_filepath:
+          type: string
+          description: >-
+            Path relative to the agent's skills directory, for example
+            `analyst-conventions/SKILL.md` or
+            `analyst-conventions/reference/glossary.md`.
+        file_contents:
+          type: string
+          description: >-
+            A `SKILL.md` is re-emitted with only a quoted `name` and
+            `description` in its frontmatter; reference files are served raw.
+            Absent when the agent was fetched with `skills=summary`.
+        name:
+          type: string
+          description: A `SKILL.md`'s name. Only in the `skills=summary` view.
+        description:
+          type: string
+          description: A `SKILL.md`'s description. Only in the `skills=summary` view.
+        bytes:
+          type: integer
+          description: Size of `file_contents` in UTF-8 bytes. Only in the `skills=summary` view.
+
+    AgentSkillRead:
+      type: object
+      readOnly: true
+      description: One agent skill file, with the pin of the definition it belongs to.
+      properties:
+        relative_filepath:
+          type: string
+        file_contents:
+          type: string
+        source:
+          $ref: "#/components/schemas/AgentSource"
+
+    AgentSource:
+      type: object
+      readOnly: true
+      description: What a resolved agent was read from, so a runner can prove which bytes ran.
+      properties:
+        environment:
+          type: string
+        package:
+          type: string
+        sourceContentSha:
+          type: string
+          description: The package's `sourceContentSha` at the load this definition came from.
+        definitionSha:
+          type: string
+          description: >-
+            SHA-256 over this agent's canonical config, instructions, skill
+            files and task files. Editing another agent, or a model, does not
+            move it.
+        servedRevision:
+          type: string
+          description: The package's `servedRevision` at the load this definition came from.
+
+    Agent:
+      type: object
+      readOnly: true
+      description: >-
+        An agent a package declares, resolved to its instructions, skill files
+        and schedules. Adopt it only when the user asks for it by name.
+      properties:
+        name:
+          type: string
+        description:
+          type: string
+        model:
+          type: string
+          description: The model the agent asks for; `inherit` when the manifest sets none.
+        instructions:
+          type: string
+          description: The instructions file's Markdown, at most 16 KB.
+        skills:
+          type: array
+          description: The agent's own skill files, sorted by `relative_filepath`.
+          items:
+            $ref: "#/components/schemas/AgentSkillFile"
+        schedules:
+          type: array
+          items:
+            $ref: "#/components/schemas/AgentSchedule"
+        warnings:
+          type: array
+          items:
+            type: string
+        source:
+          $ref: "#/components/schemas/AgentSource"
+
+    SkillSummary:
+      type: object
+      readOnly: true
+      description: >-
+        One agent skill in force for a package, without its body. This is what
+        a caller reads to decide which skill to fetch.
+      properties:
+        name:
+          type: string
+          description: >-
+            The skill's name, and the identifier for fetching it. A name
+            containing a slash (`<skill>/<stem>`) is one skill's on-demand
+            reference file rather than a skill in its own right.
+        description:
+          type: string
+          description: >-
+            One line saying when to read this skill. Empty when the package
+            author omitted it, which is also reported as a package warning.
+        origin:
+          type: string
+          enum:
+            - bundled
+            - package
+          description: >-
+            `bundled` = shipped with this server. `package` = shipped by the
+            package under `skills/`, which includes a package skill whose name
+            matches a bundled one and therefore REPLACES it for this package.
+            Present so a caller can tell a replaced skill from the original,
+            which is otherwise invisible.
+
+    Skill:
+      type: object
+      readOnly: true
+      description: An agent skill with its full Markdown body.
+      properties:
+        name:
+          type: string
+          description: The skill's name.
+        description:
+          type: string
+          description: One line saying when to read this skill.
+        content:
+          type: string
+          description: The skill's full guidance, Markdown.
+        origin:
+          type: string
+          enum:
+            - bundled
+            - package
+          description: Where this skill came from. See SkillSummary.origin.
 
     PackageEmbeddingIndex:
       type: object

package/dist/app/assets/{EnvironmentPage-1dxk_vne.js → EnvironmentPage-DaNUmaHg.js}

@@ -1 +1 @@
-import{b as r,C as t,j as e,ab as i,ax as o}from"./index-CDTd6FbM.js";function m(){const s=r(),{environmentName:n}=t();if(n){const a=i({environmentName:n});return e.jsx(o,{onSelectPackage:s,resourceUri:a})}else return e.jsx("div",{children:e.jsx("h2",{children:"Missing environment name"})})}export{m as default};
+import{w as r,D as t,j as e,ab as i,ax as o}from"./index-BK0mbcyQ.js";function m(){const s=r(),{environmentName:n}=t();if(n){const a=i({environmentName:n});return e.jsx(o,{onSelectPackage:s,resourceUri:a})}else return e.jsx("div",{children:e.jsx("h2",{children:"Missing environment name"})})}export{m as default};

package/dist/app/assets/{HomePage-DOCeWyiv.js → HomePage-CRLoVDIs.js}

@@ -1 +1 @@
-import{b as t,j as o,$ as a}from"./index-CDTd6FbM.js";function s(){const n=t();return o.jsx(a,{onClickEnvironment:n})}export{s as default};
+import{w as t,j as o,A as a}from"./index-BK0mbcyQ.js";function s(){const n=t();return o.jsx(a,{onClickEnvironment:n})}export{s as default};