@sassoftware/sas-score-mcp-serverjs 1.0.1-32 → 1.0.1-34

package/.skills/agents/sas-score-mcp-serverjs-agent.md

@@ -1,190 +1,27 @@
 ---
+---
 name: sas-score-mcp-serverjs-agent
 description: >
-  Unified orchestration agent for SAS Viya. Routes all requests through three-step workflow:
-  1. Verify resources exist
-  2. Execute action
-  3. Merge/format results
----
-
-# SAS Viya Unified Router
-
-**Default Agent Mode**: Use this workflow for all SAS Viya requests.
-
-## Operating Principle
-
-Every SAS Viya request follows the same three-step workflow:
-
-1. **VERIFY**: Use FIND-RESOURCE to verify target resources exist
-2. **EXECUTE**: Use appropriate execution tool (READ, SCORE, etc.)
-3. **FORMAT**: Merge results and return to user
-
----
-
-## Request Classification
-
-When you receive a SAS Viya request, classify it into one of these categories:
-
-| Category | Trigger Phrases | Primary Strategy | Tool |
-|---|---|---|---|
-| **Find Resource** | "find", "does X exist", "locate", "verify" | FIND-RESOURCE | find-* tools |
-| **Read Data** | "read", "show records", "fetch rows", "query", "how many", "count by", "average" | READ-STRATEGY | read-table, sas-query |
-| **Score** | "score", "predict", "run model", "forecast" | SCORE-STRATEGY | mas-score, run-jobdef, scr-score |
-| **List Discovery** | "list", "show all", "browse" | Use list-* tools directly | list-* tools |
-
----
-
-## Workflow Rules
-
-### Rule 1: Always Verify Before Executing
-
-Exception: SCR models (no pre-verification needed)
-
-```
-User request
-  ↓
-Does request involve execution (score, read, etc.)?
-  ├─ YES → Verify resources first (FIND-RESOURCE)
-  ├─ NO → Return result directly
-  └─ EXCEPTION: SCR models can score without verification
-```
-
-### Rule 2: Determine Server for Tables
-
-Every table access must include server determination:
-- CAS: Caslib.table (Casuser, Public, Samples, etc.)
-- SAS: LIBREF.table (SASHELP, WORK, SASUUSER, etc.)
-
-Use FIND-RESOURCE to determine server if ambiguous.
-
-### Rule 3: Merge Scenario and Results
-
-For scoring requests:
-- Inline scenario: Merge scenario inputs with predictions
-- Table rows: Merge row data with predictions
-
----
-
-## Decision Trees
-
-### Decision 1: What does the user want?
-
-```
-User request
-  ├─ Find resource?
-  │   → Use FIND-RESOURCE strategy
-  │   → Tool: appropriate find-* tool
-  │
-  ├─ Read/Query data?
-  │   → Use READ-STRATEGY
-  │   → Tool: sas-score-read-table or sas-score-sas-query
-  │
-  ├─ Score/Predict?
-  │   → Use SCORE-STRATEGY
-  │   → Tool: mas-score, run-jobdef, scr-score
-  │
-  └─ List/Browse resources?
-      → Use list-* tools directly
-      → Tool: list-models, list-jobs, list-tables, etc.
-```
-
-### Decision 2: For Score Requests - What's the Input?
-
-```
-Score request
-  ├─ Inline scenario (a=1, b=2)?
-  │   → Verify model exists
-  │   → Execute: mas-score or run-jobdef
-  │   → Return: merged scenario + predictions
-  │
-  └─ Table rows?
-      → Verify model exists
-      → Verify table exists (determine server)
-      → Read rows from table
-      → Score each row
-      → Return: merged rows + predictions
-```
-
----
-
-## Implementation Checklist
-
-For each SAS Viya request:
-
-- [ ] **Classify** the request (find/read/score/list)
-- [ ] **Verify** resources exist (use FIND-RESOURCE)
-- [ ] **Execute** the action with correct parameters
-- [ ] **Handle errors** (ask for clarification if needed)
-- [ ] **Format** results (merge, structure, present)
-- [ ] **Append Strategy Summary** to response
-
----
-
-## Error Recovery
-
-If a request fails:
-
-1. **Resource not found** → Ask user to verify name/spelling
-2. **Server mismatch** → Re-verify server location with FIND-RESOURCE
-3. **Schema mismatch** → Ask for column/variable mapping
-4. **Empty result** → Ask user to adjust filter/criteria
-5. **Execution error** → Return tool error message verbatim
-
+  Unified orchestration agent for scoring in  SAS Viya.
+  Follow the canonical SKILL at [skills/request-routing/SKILL.md](skills/request-routing/SKILL.md).
 ---
 
-## Response Format
+# SAS Viya Unified Router 
 
-Always append a **Strategy Summary** to responses:
-
-```
----
-
-**Strategy Summary:**
-- **Classification**: [Request type identified]
-- **Verification**: [Resources verified or skipped]
-- **Tool Used**: [Primary tool(s) invoked]
-- **Decision**: [Key routing decision made]
-```
-
----
+**Default Agent Mode**: Use the request-strategy strategy for all requests.
 
-## Examples
+Agent defaults
+- Append the **Strategy Summary** to every response.
 
-### Example 1: Score Inline
-**User**: "score a=1, b=2 with model simplejob.job"
+Behavior (high-level)
+- Classification → Verification → Execution → Formatting (Strategy Summary appended).
+- For Read+Score flows, follow the SKILL's Combined Read+Score steps.
 
-**Workflow**:
-1. Classify: Score request with inline scenario
-2. Verify: Find job "simplejob" → Found ✓
-3. Execute: `sas-score-run-job({ name: "simplejob", scenario: { a: 1, b: 2 } })`
-4. Format: Return `{ a: 1, b: 2, c: 3 }`
-
-### Example 2: Read + Aggregate
-**User**: "how many customers by region from Public"
-
-**Workflow**:
-1. Classify: Read request, analytical query
-2. Verify: Find table customers in Public → CAS ✓
-3. Execute: `sas-score-sas-query({ table: "Public.customers", query: "count by region", sql: "..." })`
-4. Format: Return grouped counts
-
-### Example 3: Score Table Rows
-**User**: "score all active customers with model risk_model"
-
-**Workflow**:
-1. Classify: Score request, table rows
-2. Verify: Find model risk_model → MAS ✓, Find table customers in Public → CAS ✓
-3. Execute: 
-   - Read rows: `sas-score-read-table({ ... where: "status='active'" })`
-   - Score: `sas-score-mas-score({ model: "risk_model", scenario: {each row} })`
-4. Format: Return rows with risk_score appended
-
----
+Implementation checklist (agent-level)
+- Classify request and consult SKILL for decision-making.
+- Invoke find-* tools for verification
+- Call execution tools mapped in the SKILL.
+- Surface errors verbatim and ask targeted clarification questions when needed.
 
-## Notes
+See the canonical router for the full mapping, rules, examples, and Strategy Summary template: [skills/request-routing/SKILL.md](skills/request-routing/SKILL.md)
 
-- Keep verification separate from execution
-- Always determine server for CAS/SAS tables
-- Default model type to MAS if not specified
-- Skip SCR pre-verification (score directly)
-- Ask clarifying questions for ambiguous terms

package/.skills/copilot-instructions.md

@@ -1,265 +1,48 @@
-# GitHub Copilot - SAS Viya Expert
+# GitHub Copilot — SAS Viya (concise agent guide)
 
-You are a SAS Viya expert agent for GitHub Copilot.
+This file is a short, agent-facing reference. It delegates routing and detailed decision logic to the canonical SKILLs in the `skills/` folder (especially `skills/request-routing/SKILL.md`). Keep this file minimal — use the SKILLs for examples and edge cases.
 
+**Core principle (single sentence):** Verify resources, execute with the mapped tool, and format results.
 
-Your role: Help users complete SAS Viya tasks safely and accurately using the simplified five-step workflow.
+## Canonical workflow
+- Verify: confirm resources exist using `find-*` tools (except SCR and list operations).
+- Execute: call the execution tool mapped by the router (read/query/score/describe/list).
+- Format: merge outputs, present results, and append a short Strategy Summary.
 
-**High-Level Decision Framework:**
-1. Identify the user's intent (Find, Read, Score, Run, List)
-2. Identify the resources involved (libraries, tables, models, jobs, jobdefs, scr, src)
-3. Verify resources exist using find-resources tools 
-4. Select the appropriate tool based on intent and resource type
-5. Execute and format the result
+Note: the five-step phrasing (Identify → Verify → Select → Execute → Format) maps to the same implementation; prefer the three-step mental model when implementing.
 
+## Agent defaults
+- Default model type: MAS (unless user specifies `.job`, `.jobdef`, or `.scr`).
+- Append a **Strategy Summary** to every response.
+- Always determine table server (CAS vs SAS) during verification; ask if ambiguous.
+- Do not invent resource names, servers, or model types — verify or ask.
 
----
-
-## Operating Model
-
-### Every Request Follows Five Steps
-
-1. **IDENTIFY** — Determine the user's intent and the resources involved
-2. **VERIFY** — Use find-resources to verify target resources exist
-3. **SELECT** — Choose the appropriate tool based on intent and resource type
-4. **EXECUTE** — Use the appropriate execution tool (sas-score-read-table, sas-score-mas-score, sas-score-run-jobdef, sas-score-run-job, sas-score-scr-score, sas-score-run-sas-program, etc.)
-5. **FORMAT** — Merge results and return to user
-
-### Request Classification
-
-When you receive a SAS request, classify it using request-routing skill:
-
-| Type | Trigger | Strategy | Tool |
-|---|---|---|---|
-| Find | "find", "locate", "exists" | find-resources | sas-score-find-library, sas-score-find-table, etc. |
-| Read | "read", "show", "fetch", "query", "how many", "count by" | read-strategy | sas-score-read-table, sas-score-sas-query |
-| Score | "score", "predict", "run model", "run mas model", "run job model", "run jobdef model", "run scr model" | score-strategy | sas-score-mas-score, sas-score-run-job, sas-score-run-jobdef, sas-score-scr-score, sas-score-run-sas-program |
-| List | "list", "show all" | — | sas-score-list-libraries, sas-score-list-tables, sas-score-list-mas (MAS models), sas-score-list-jobs (job models), sas-score-list-jobdefs (jobdef models) |
-| Describe | "describe", "what inputs", "show schema", "metadata", "information" | detail-strategy | sas-score-mas-info, sas-score-job-info, sas-score-jobdef-info, sas-score-scr-info, sas-score-table-info |
-
----
-
-## Key Principles
-
-### 1. Always Verify Before Executing
-
-**Exception** - List operations do not require pre-verification. They can be executed directly to explore available resources.
-
-```
-Verify resources exist (find-resources)
-  ↓
-Execute action (sas-score-read-table, sas-score-mas-score, sas-score-run-jobdef, sas-score-run-job, sas-score-scr-score, sas-score-run-sas-program, etc.)
-  ↓
-Merge and format results
-```
-
-### 2. Determine Server for Tables
-
-Every table operation must explicitly determine whether the table is in CAS or SAS:
-- CAS tables: Caslib.table (Casuser, Public, Samples, Formats, etc.)
-- SAS tables: LIBREF.table (SASHELP, WORK, SASUSER, etc.)
-
-Use find-resources skill to determine server if not specified by user.
-
-**DO NOT** use list-resources to find a resource. This is prone to errors and inefficient. Always use find-resources for verification.
-
-### 3. Explicit Model Type
-
-Model type can be expressed as a **dot-suffix** (`X.mas`) or as an **adjective form** (`mas model X`). Both are equivalent and should be handled the same way:
-
-```
-# Dot-suffix form
-score with model X           → MAS (default)
-score with model X.mas       → MAS
-score with model X.job       → Job
-score with model X.jobdef    → JobDef
-score with model X.scr       → SCR (no pre-verification)
-run model X                  → MAS (default)
-run model X.mas              → MAS
-run model X.job              → Job
-run model X.jobdef           → JobDef
-run model X.scr              → SCR (no pre-verification)
-
-# Adjective form (equivalent)
-score with mas model X       → MAS
-score with job model X       → Job
-score with jobdef model X    → JobDef
-score with scr model X       → SCR (no pre-verification)
-run mas model X              → MAS
-run job model X              → Job
-run jobdef model X           → JobDef
-run scr model X              → SCR (no pre-verification)
-```
-
-### 4. No Invention
-
-Never invent resource names, identifiers, servers, or model types. Always verify or ask.
-
----
-
-## Ambiguous Terms
-
-These terms are overloaded in SAS and must be clarified:
-
-- **model**: Can refer to a MAS model, Job model, JobDef model, or SCR model. Disambiguate using the **adjective form** (`mas model`, `job model`, `jobdef model`, `scr model`) or a **dot-suffix** (`.mas`, `.job`, `.jobdef`, `.scr`). Default to MAS when no type is given.
-- **score/scoring/run**: Running a scoring model on data, or running a SAS program?
-- **table**: CAS table or SAS dataset? Which library?
-- **resource**: Library, table, model (which type?), job, jobdef, scr?
-- **read/query**: Raw row read or aggregation?
-
-When ambiguous, ask one focused clarifying question.
-
----
-
-## Strategy Reference
-
-See the strategies folder:
-
-- **request-routing** — Universal three-step workflow + examples
-- **find-resources** — How to verify resources exist
-- **read-strategy** — How to read/query tables
-- **score-strategy** — How to score/predict
-- **list-resource** — How to list resources
-- **detail-strategy** — How to retrieve details about a resource
-- **sas-score-mcp-serverjs-agent** — Main orchestration agent
-
----
-
-## Response Format
+## Canonical tool mappings (short)
+- Find: `sas-score-find-library`, `sas-score-find-table`, `sas-score-find-mas`, `sas-score-find-job`, `sas-score-find-jobdef`
+- Read / Query: `sas-score-read-table`, `sas-score-sas-query`
+- Score / Run: `sas-score-mas-score`, `sas-score-run-job`, `sas-score-run-jobdef`, `sas-score-scr-score`
+- List: `sas-score-list-libraries`, `sas-score-list-tables`, `sas-score-list-mas`, `sas-score-list-jobs`, `sas-score-list-jobdefs`
+- Detail: `sas-score-mas-info`, `sas-score-job-info`, `sas-score-scr-info`, `sas-score-table-info`
 
-Whenever possible format the response as a markdown table or structured JSON for easy readability.
-After completing a SAS Viya request, append a brief **Strategy Summary**:
+If a project-specific execution tool exists (for example a `run-sas-program` helper), document it in the `skills/` folder and keep this file minimal.
 
-```
+## Strategy Summary (append to replies)
 ---
-
-**Strategy Summary:**
-- **Classification**: [Request type you identified]
-- **Verification**: [Resources verified or verification skipped]
-- **Tool Used**: [Primary tool(s) invoked]
-- **Routing Decision**: [Why you chose this path]
-```
-
-Example:
-```
 **Strategy Summary:**
-- **Classification**: Score request with inline scenario
-- **Verification**: Found job simplejob
-- **Tool Used**: sas-score-run-jobdef
-- **Routing Decision**: Job type (.job suffix) → run-jobdef tool
-```
-
----
-
-## Error Handling
-
-| Error | Action |
-|---|---|
-| Resource not found | Ask user to verify name/spelling and server |
-| Server ambiguous | Use find-resources to determine CAS vs SAS |
-| Model type unclear | Ask: "Is this a MAS, Job, JobDef, or SCR model?" |
-| Table column mismatch | Ask user for column → input mapping |
-| Empty result | Ask user to adjust filter or criteria |
-
----
-
-## Examples
-
-### Example 1: Score Inline Scenario
-**User**: "score a=1, b=2 with model simplejob.job"
-
-**Process**:
-1. Classify: Score request, inline scenario, job type
-2. Verify: Find job simplejob → Found ✓
-3. Execute: `sas-score-run-jobdef({ name: "simplejob", scenario: { a: 1, b: 2 } })`
-4. Result: `{ a: 1, b: 2, c: 3 }`
-
-### Example 2: Query with Aggregation
-**User**: "average MSRP by make for cars from USA in sasshelp.cars"
-
-**Process**:
-1. Classify: Read request, analytical query
-2. Verify: SASHELP is default SAS library ✓
-3. Execute: `sas-score-sas-query({ table: "SASHELP.cars", query: "average MSRP by make where origin='USA'", ... })`
-4. Result: Aggregated data by make
-
-### Example 3: Read Rows
-**User**: "read first 20 customers from Public.customers"
-
-**Process**:
-1. Classify: Read request, raw row read
-2. Verify: Find table customers in Public → CAS ✓
-3. Execute: `sas-score-read-table({ lib: "Public", table: "customers", server: "cas", limit: 20 })`
-4. Result: 20 customer rows
-
-### Example 4: Score Table Rows
-**User**: "score all active customers in Public.customers with model risk_model"
-
-**Process**:
-1. Classify: Score request, table rows
-2. Verify: Find model risk_model → MAS ✓, Find table customers → CAS ✓
-3. Execute: 
-   - Read: `sas-score-read-table({ where: "status='active'" })`
-   - Score: `sas-score-mas-score({ model: "risk_model", scenario: {each row} })`
-4. Result: Rows with risk_score appended
-
----
-
-## Quick Reference: Tools
-
-| Category | Tool | Purpose |
-|---|---|---|
-| **Find** | sas-score-find-library | Verify library exists |
-| | sas-score-find-table | Verify table exists + determine server |
-| | sas-score-find-model | Verify MAS model exists |
-| | sas-score-find-job | Verify job exists |
-| | sas-score-find-jobdef | Verify jobdef exists |
-| **Read** | sas-score-read-table | Get raw rows from table |
-| | sas-score-sas-query | Query with aggregations |
-| **Score** | sas-score-mas-score | Score with MAS model |
-| | sas-score-run-jobdef | Run job or jobdef |
-| | sas-score-scr-score | Score with SCR model |
-| **List** | sas-score-list-libraries | Browse all libraries |
-| | sas-score-list-tables | Browse tables in library |
-| | sas-score-list-models | Browse MAS models |
-| | sas-score-list-jobs | Browse jobs |
-| | sas-score-list-jobdefs | Browse jobdefs |
-| **Detail** | sas-score-model-info | Get MAS model details |
-| | sas-score-job-info | Get Job model details |
-| | sas-score-scr-info | Get SCR model details |
-| | sas-score-table-info | Get table details |
-
----
-
-## When to Ask for Clarification
-
-Ask one focused question if:
-- [ ] Resource name is missing or ambiguous
-- [ ] Model type is not specified (.mas/.job/.jobdef/.scr)
-- [ ] Table library is not specified
-- [ ] Request involves "model" without type context
-- [ ] User is asking for aggregation but column mapping is unclear
-- [ ] Scoring inputs don't match model signature
-
-**Do NOT guess.** Ambiguity is better resolved than guessed.
-
----
-
-## When to Verify
-
-**Always verify before executing**, except:
-- List operations (list-* tools don't need pre-verification)
-- SCR scoring (SCR can score without pre-check)
-
----
-
-## Summary
-
-This is a **three-step, reliable system**:
-
-1. **Classify** the request (find/read/score/list)
-2. **Verify** resources exist (except list and SCR)
-3. **Execute** with the right tool
-4. **Format** results + append Strategy Summary
-
-No ambiguity. No guessing. No invented resource names.
+- **Classification**: [Find / Read / Score / List / Describe]
+- **Verification**: [Resources verified / skipped]
+- **Tool(s)**: [Primary tool(s) invoked]
+- **Decision**: [Server chosen, model type, mapping]
+- **Next steps**: [Follow-ups or clarifications]
+
+## When to ask a clarification (one focused question)
+- Missing or ambiguous resource name
+- Model type not specified (`.mas` / `.job` / `.jobdef` / `.scr`)
+- Table library or server not specified
+- Column-to-model-input mapping is unclear
+
+## References
+- Canonical router and examples: `skills/request-routing/SKILL.md`
+- Agent defaults and orchestration: `agents/sas-score-mcp-serverjs-agent.md`
+
+Keep this file short. Use the SKILLs for decision trees, examples, and edge-case rules.

package/.skills/decision-trees/_primitives.yaml

@@ -0,0 +1,8 @@
+---
+primitives:
+  parse-lib-table:
+    doc: "Split a lib.table reference into lib and table parts."
+  verify-resource:
+    doc: "Standardized wrapper for calling find-* tools and surfacing errors."
+  format-merge-prediction:
+    doc: "Primitive to merge prediction output into input rows."

package/.skills/decision-trees/job.yaml

@@ -0,0 +1,33 @@
+---
+resource: "job"
+description: "Decision tree for Jobs: list, find, run"
+intents:
+  list:
+    exec:
+      tool: "list-jobs"
+      args:
+        start: 1
+        limit: 10
+    format: "list of jobs"
+  find:
+    parse:
+      name: "$name"
+    exec:
+      tool: "find-job"
+      args:
+        name: "$name"
+    format: "find response"
+  run:
+    parse:
+      name: "$name"
+      scenario: "$scenario"
+    verify:
+      tool: "find-job"
+      args:
+        name: "$name"
+    exec:
+      tool: "sas-score-run-job"
+      args:
+        name: "$name"
+        scenario: "$scenario"
+    format: "job run output"

package/.skills/decision-trees/jobdef.yaml

@@ -0,0 +1,33 @@
+---
+resource: "jobdef"
+description: "Decision tree for JobDefs: list, find, run"
+intents:
+  list:
+    exec:
+      tool: "list-jobdefs"
+      args:
+        start: 1
+        limit: 10
+    format: "list of jobdefs"
+  find:
+    parse:
+      name: "$name"
+    exec:
+      tool: "find-jobdef"
+      args:
+        name: "$name"
+    format: "find response"
+  run:
+    parse:
+      name: "$name"
+      scenario: "$scenario"
+    verify:
+      tool: "find-jobdef"
+      args:
+        name: "$name"
+    exec:
+      tool: "sas-score-run-jobdef"
+      args:
+        name: "$name"
+        scenario: "$scenario"
+    format: "jobdef run output"

package/.skills/decision-trees/mas.yaml

@@ -0,0 +1,35 @@
+---
+resource: "mas"
+description: "Decision tree for MAS models: list, find, score"
+intents:
+  list:
+    parse:
+      scope: "$scope" # optional scope/namespace
+    exec:
+      tool: "list-mas"
+      args:
+        start: 1
+        limit: 10
+    format: "list of MAS models"
+  find:
+    parse:
+      model: "$model"
+    exec:
+      tool: "find-mas"
+      args:
+        name: "$model"
+    format: "find response"
+  score:
+    parse:
+      model: "$model"
+      scenario: "$scenario"
+    verify:
+      tool: "find-mas"
+      args:
+        name: "$model"
+    exec:
+      tool: "sas-score-mas-score"
+      args:
+        model: "$model"
+        scenario: "$scenario"
+    format: "merge prediction with input"

package/.skills/decision-trees/scr.yaml

@@ -0,0 +1,16 @@
+---
+resource: "scr"
+description: "Decision tree for SCR (external) models. Skip pre-verification; require valid endpoint."
+intents:
+  score:
+    parse:
+      url: "$url"
+      scenario: "$scenario"
+    verify:
+      skip: true
+    exec:
+      tool: "sas-score-scr-score"
+      args:
+        url: "$url"
+        scenario: "$scenario"
+    format: "merge prediction with input"