Add per-agent Skills management and spawn load state

backend/__tests__/service/skills.test.js

@@ -3,13 +3,25 @@ const request = require('supertest');
 const jwt = require('jsonwebtoken');
 const Pod = require('../../models/Pod');
 const PodAsset = require('../../models/PodAsset');
+const PodAssetService = require('../../services/podAssetService').default;
 const User = require('../../models/User');
+const { AgentInstallation } = require('../../models/AgentRegistry');
+const AgentIdentityService = require('../../services/agentIdentityService');
+const { issueRuntimeTokenForAgent } = require('../../routes/registry/tokens');
+const agentsRuntimeRoutes = require('../../routes/agentsRuntime');
 const skillsRoutes = require('../../routes/skills');
 const { setupMongoDb, closeMongoDb } = require('../utils/testUtils');
 
 const JWT_SECRET = 'test-jwt-secret';
 
 describe('Skills Catalog Routes', () => {
+  test('normalizes long punctuation runs without changing scoped skill keys', () => {
+    expect(PodAssetService.normalizeSkillKey(`${'-'.repeat(100_000)}Focus---Mode${'-'.repeat(100_000)}`))
+      .toBe('focus-mode');
+    expect(PodAssetService.buildScopedSkillKey({ name: 'Focus Mode', scope: 'agent', agentName: 'Scout', instanceId: 'default' }))
+      .toBe('focus-mode-scout-default');
+  });
+
   let app;
   let authToken;
   let userId;
@@ -21,6 +33,7 @@ describe('Skills Catalog Routes', () => {
     app = express();
     app.use(express.json());
     app.use('/api/skills', skillsRoutes);
+    app.use('/api/agents/runtime', agentsRuntimeRoutes);
 
     const user = await User.create({
       username: 'skilluser',
@@ -81,4 +94,85 @@ describe('Skills Catalog Routes', () => {
     expect(asset).toBeTruthy();
     expect(asset.metadata.license).toBe('MIT');
   });
+
+  test('only the installer or instance admin can add and remove agent skills', async () => {
+    const member = await User.create({ username: 'skillmember', email: 'skillmember@example.com', password: 'password123' });
+    await Pod.updateOne({ _id: podId }, { $push: { members: member._id } });
+    const memberToken = jwt.sign({ id: member._id.toString() }, JWT_SECRET);
+    await AgentInstallation.create({ agentName: 'scout', instanceId: 'default', podId, version: '1.0.0', installedBy: userId });
+    const body = { podId, name: 'Review', content: '# Review', scope: 'agent', agentName: 'scout', instanceId: 'default' };
+
+    const deniedAdd = await request(app).post('/api/skills/import').set('Authorization', `Bearer ${memberToken}`).send(body);
+    expect(deniedAdd.status).toBe(403);
+    expect(await PodAsset.countDocuments({ podId, type: 'skill', 'metadata.skillName': 'Review' })).toBe(0);
+
+    const admin = await User.create({ username: 'skilladmin', email: 'skilladmin@example.com', password: 'password123', role: 'admin' });
+    await Pod.updateOne({ _id: podId }, { $push: { members: admin._id } });
+    const adminToken = jwt.sign({ id: admin._id.toString() }, JWT_SECRET);
+    const adminAdd = await request(app).post('/api/skills/import').set('Authorization', `Bearer ${adminToken}`)
+      .send({ ...body, name: 'Admin review' });
+    expect(adminAdd.status).toBe(201);
+
+    const added = await request(app).post('/api/skills/import').set('Authorization', `Bearer ${authToken}`).send(body);
+    expect(added.status).toBe(201);
+    const url = `/api/skills/pods/${podId}/imported?scope=agent&agentName=scout&instanceId=default&name=Review`;
+    const deniedRemove = await request(app).delete(url).set('Authorization', `Bearer ${memberToken}`);
+    expect(deniedRemove.status).toBe(403);
+    expect(await PodAsset.countDocuments({ podId, status: 'active', 'metadata.skillName': 'Review' })).toBe(1);
+
+    const removed = await request(app).delete(url).set('Authorization', `Bearer ${authToken}`);
+    expect(removed.status).toBe(200);
+    expect(await PodAsset.countDocuments({ podId, status: 'active', 'metadata.skillName': 'Review' })).toBe(0);
+  });
+
+  test('records mounted names for the authenticated agent and returns them to the page', async () => {
+    await request(app).post('/api/skills/import').set('Authorization', `Bearer ${authToken}`)
+      .send({ podId, name: 'review', content: '# Review', scope: 'agent', agentName: 'scout', instanceId: 'default' });
+    await request(app).post('/api/skills/import').set('Authorization', `Bearer ${authToken}`)
+      .send({ podId, name: 'local-only', content: '# Local', metadataOnly: true, scope: 'agent', agentName: 'scout', instanceId: 'default' });
+    const installation = await AgentInstallation.findOne({ podId, agentName: 'scout' });
+    const agentUser = await AgentIdentityService.getOrCreateAgentUser('scout', { instanceId: 'default' });
+    const { token } = await issueRuntimeTokenForAgent(agentUser, 'test skill mount', installation);
+    const feed = await request(app).get(`/api/agents/runtime/pods/${podId}/skills`)
+      .set('Authorization', `Bearer ${token}`);
+    expect(feed.status).toBe(200);
+    expect(feed.body.items).toEqual(expect.arrayContaining([
+      expect.objectContaining({ name: 'review', content: '# Review' }),
+    ]));
+    expect(feed.body.items.map((item) => item.name)).not.toContain('local-only');
+    const path = `/api/agents/runtime/pods/${podId}/skill-load`;
+    const posted = await request(app).post(path).set('Authorization', `Bearer ${token}`)
+      .send({ mounted: ['review', 'private-operator-skill'], conflicted: ['draft'] });
+    expect(posted.status).toBe(200);
+    const installAfter = await AgentInstallation.findById(installation._id).lean();
+    expect(installAfter.skillLoad).toMatchObject({ mounted: ['review', 'private-operator-skill'], conflicted: ['draft'] });
+    expect(installAfter.skillLoad.at).toBeInstanceOf(Date);
+
+    const read = await request(app).get(`/api/skills/pods/${podId}/imported?scope=agent&agentName=scout&instanceId=default`)
+      .set('Authorization', `Bearer ${authToken}`);
+    expect(read.status).toBe(200);
+    expect(read.body.skillLoad).toMatchObject({ mounted: ['review'], conflicted: [] });
+    expect(JSON.stringify(read.body)).not.toContain('private-operator-skill');
+    expect(read.body.canEdit).toBe(true);
+
+    const unavailable = await request(app).post(path).set('Authorization', `Bearer ${token}`)
+      .send({ mounted: [], conflicted: [], status: 'unavailable' });
+    expect(unavailable.status).toBe(200);
+    const unavailableRead = await request(app).get(`/api/skills/pods/${podId}/imported?scope=agent&agentName=scout&instanceId=default`)
+      .set('Authorization', `Bearer ${authToken}`);
+    expect(unavailableRead.body.skillLoad).toMatchObject({ status: 'unavailable', mounted: [], conflicted: [] });
+
+    const invalid = await request(app).post(path).set('Authorization', `Bearer ${token}`)
+      .send({ mounted: ['/private/skill'], conflicted: [] });
+    expect(invalid.status).toBe(400);
+    expect((await AgentInstallation.findById(installation._id).lean()).skillLoad.status)
+      .toBe('unavailable');
+
+    await request(app).delete(`/api/skills/pods/${podId}/imported?scope=agent&agentName=scout&instanceId=default&name=review`)
+      .set('Authorization', `Bearer ${authToken}`);
+    const afterRemove = await request(app).get(`/api/agents/runtime/pods/${podId}/skills`)
+      .set('Authorization', `Bearer ${token}`);
+    expect(afterRemove.status).toBe(200);
+    expect(afterRemove.body.items.map((item) => item.name)).not.toContain('review');
+  });
 });

backend/__tests__/unit/routes/routeRateLimitGuard.baseline.json

@@ -163,7 +163,6 @@
   "routes/skills.ts GET /:skillId/ratings/summary [unlimited]",
   "routes/skills.ts GET /catalog [unlimited]",
   "routes/skills.ts GET /gateway-credentials [unlimited]",
-  "routes/skills.ts GET /pods/:podId/imported [unlimited]",
   "routes/skills.ts GET /ratings/summary [unlimited]",
   "routes/skills.ts GET /requirements [unlimited]",
   "routes/skills.ts PATCH /gateway-credentials [unlimited]",

backend/__tests__/unit/routes/skills.import-source-guard.test.js

@@ -38,15 +38,16 @@ const GITHUB_SOURCE = 'https://github.com/acme/skills/blob/main/skills/notes/SKI
 const RAW_SOURCE = 'https://raw.githubusercontent.com/acme/skills/main/skills/notes/SKILL.md';
 const LISTING_URL = 'https://api.github.com/repos/acme/skills/contents/skills/notes?ref=main';
 
-const importBody = (overrides) => ({ podId: 'pod-1', name: 'notes', ...overrides });
+const POD_ID = '507f1f77bcf86cd799439011';
+const importBody = (overrides) => ({ podId: POD_ID, name: 'notes', ...overrides });
 
 describe('skill source fetches are confined to GitHub', () => {
   let fetchSpy;
   // url -> Response factory; any URL not listed fails the test loudly.
   let routes;
 
   beforeEach(() => {
-    const pod = { _id: 'pod-1', createdBy: 'user-1', members: [] };
+    const pod = { _id: POD_ID, createdBy: 'user-1', members: [] };
     Pod.findById.mockReturnValue({ lean: jest.fn().mockResolvedValue(pod) });
     AgentInstallation.find.mockReturnValue({ lean: jest.fn().mockResolvedValue([]) });
     PodAssetService.upsertImportedSkillAsset.mockResolvedValue({ _id: 'asset-1' });

backend/__tests__/unit/routes/skills.source-unavailable.test.js

@@ -43,7 +43,8 @@ const GITHUB_SOURCE = 'https://github.com/acme/skills/blob/main/skills/notes/SKI
 const RAW_SOURCE = 'https://raw.githubusercontent.com/acme/skills/main/skills/notes/SKILL.md';
 const LISTING_URL = 'https://api.github.com/repos/acme/skills/contents/skills/notes?ref=main';
 
-const importBody = (overrides) => ({ podId: 'pod-1', name: 'notes', ...overrides });
+const POD_ID = '507f1f77bcf86cd799439011';
+const importBody = (overrides) => ({ podId: POD_ID, name: 'notes', ...overrides });
 
 const LEGACY_SOURCE = 'https://github.com/openclaw/skills/tree/main/skills/acme/notes/SKILL.md';
 const CLAWHUB_META = 'https://clawhub.ai/api/skill?owner=acme&slug=notes';
@@ -63,7 +64,7 @@ describe('a catalog source without the skill is a 404 or a 502, never a 500', ()
   let routes;
 
   beforeEach(() => {
-    const pod = { _id: 'pod-1', createdBy: 'user-1', members: [] };
+    const pod = { _id: POD_ID, createdBy: 'user-1', members: [] };
     Pod.findById.mockReturnValue({ lean: jest.fn().mockResolvedValue(pod) });
     AgentInstallation.find.mockReturnValue({ lean: jest.fn().mockResolvedValue([]) });
     PodAssetService.upsertImportedSkillAsset.mockReset();

backend/models/AgentRegistry.ts

@@ -211,6 +211,7 @@ export interface IAgentInstallationRegistry extends Document {
   errorMessage?: string;
   staleSince?: Date;
   installedBy: Types.ObjectId;
+  skillLoad?: { at: Date; mounted: string[]; conflicted: string[]; status?: 'available' | 'unavailable' };
   usage: {
     lastUsedAt?: Date;
     totalCalls: number;
@@ -248,6 +249,10 @@ const AgentInstallationSchema = new Schema<IAgentInstallationRegistry>(
     errorMessage: String,
     staleSince: { type: Date },
     installedBy: { type: Schema.Types.ObjectId, ref: 'User', required: true },
+    skillLoad: {
+      type: new Schema({ at: Date, mounted: [String], conflicted: [String], status: { type: String, enum: ['available', 'unavailable'] } }, { _id: false }),
+      default: undefined,
+    },
     usage: {
       lastUsedAt: Date,
       totalCalls: { type: Number, default: 0 },

backend/routes/agentsRuntime.ts

@@ -35,6 +35,7 @@ const Activity = require('../models/Activity');
 const User = require('../models/User');
 const Post = require('../models/Post');
 const Pod = require('../models/Pod');
+const PodAsset = require('../models/PodAsset');
 const { AgentInstallation } = require('../models/AgentRegistry');
 const File = require('../models/File');
 const { getObjectStore } = require('../services/objectStore');
@@ -1593,6 +1594,63 @@ router.post(
   },
 );
 
+// Active catalog skills are delivered at turn start so an add or remove takes
+// effect on the next spawn without rewriting the operator's local environment.
+router.get('/pods/:podId/skills', phase4RateLimit, agentRuntimeAuth, async (req: any, res: any) => {
+  try {
+    const { podId } = req.params;
+    const installation = resolveInstallationForPod(req.agentInstallations, req.agentInstallation, podId);
+    if (!installation || String(installation.podId) !== podId
+      || !ensurePodMatch(req.agentInstallations || installation, podId, req.agentAuthorizedPodIds)) {
+      return res.status(403).json({ message: 'Agent token not authorized for this pod' });
+    }
+    const assets = await PodAsset.find({ podId, type: 'skill', status: 'active', 'metadata.scope': 'agent' })
+      .select('content metadata').lean();
+    const items = assets.filter((asset: any) => {
+      const meta = asset.metadata || {};
+      return String(meta.agentName || '').toLowerCase() === String(installation.agentName).toLowerCase()
+        && String(meta.instanceId || 'default').toLowerCase() === String(installation.instanceId || 'default').toLowerCase()
+        && meta.metadataOnly !== true
+        && !String(asset.content || '').includes('Imported as metadata from a local agent');
+    }).map((asset: any) => ({
+      name: String(asset.metadata.skillName || ''),
+      content: String(asset.content || ''),
+    })).filter((item: { name: string; content: string }) => item.name && item.content);
+    return res.json({ items });
+  } catch (error) {
+    console.error('Error loading agent skills:', error);
+    return res.status(500).json({ message: 'Failed to load agent skills' });
+  }
+});
+
+// The wrapper reports what its adapter actually mounted for this spawn. Keep
+// only skill names: local source paths belong to the operator's machine.
+router.post('/pods/:podId/skill-load', phase4RateLimit, agentRuntimeAuth, async (req: any, res: any) => {
+  try {
+    const { podId } = req.params;
+    const installation = resolveInstallationForPod(req.agentInstallations, req.agentInstallation, podId);
+    if (!installation || String(installation.podId) !== podId
+      || !ensurePodMatch(req.agentInstallations || installation, podId, req.agentAuthorizedPodIds)) {
+      return res.status(403).json({ message: 'Agent token not authorized for this pod' });
+    }
+    const validNames = (value: unknown): value is string[] => Array.isArray(value)
+      && value.length <= 50
+      && value.every((name) => typeof name === 'string' && name.length > 0 && name.length <= 120 && !/[\\/]/.test(name));
+    const { mounted, conflicted, status = 'available' } = req.body || {};
+    if (!validNames(mounted) || !validNames(conflicted) || !['available', 'unavailable'].includes(status)) {
+      return res.status(400).json({ message: 'mounted and conflicted must be arrays of skill names, with a valid status' });
+    }
+    await AgentInstallation.updateOne(
+      { _id: installation._id, status: 'active' },
+      { $set: { skillLoad: { at: new Date(), mounted, conflicted, status } } },
+    );
+    return res.json({ success: true });
+  } catch (error) {
+    console.error('Error recording skill load:', error);
+    return res.status(500).json({ message: 'Failed to record skill load' });
+  }
+});
+
 router.get('/pods/:podId/context', phase4RateLimit, agentRuntimeAuth, async (req: any, res: any) => {
   try {
     const { podId } = req.params;