DeepSeek Harness: نظام الأحداث

// إصدار حدث
ctx.emit('session/created', { id: 'abc-123', user: 'Alice' })

// الاستماع للحدث
ctx.on('session/created', (data) => {
  ctx.logger.info(`new session: ${data.id}`)
})

ctx.on('session/created', (data) => {
  ctx.logger.info(`logger: ${data.id}`)
})

ctx.on('session/created', (data) => {
  ctx.metrics.inc('session_count')
})

ctx.on('session/created', (data) => {
  ctx.cache.set(`session:${data.id}`, data)
})

ctx.emit('session/created', { id: 'abc', user: 'Alice' })
// جميع المستمعين الثلاثة يُنفذون

// المستمع يمكنه "اعتراض" الحدث
ctx.on('tool/beforeExecute', (data) => {
  if (data.tool === 'shell' && data.params.command.includes('rm')) {
    return { denied: true, reason: 'dangerous command' }
  }
})

ctx.bail('tool/beforeExecute', { tool: 'shell', params: { command: 'rm -rf /' } })
// → يُعيد { denied: true, reason: 'dangerous command' }
// المستمعون اللاحقون لا يُنفذون

// إضافة سياسة الموافقة
ctx.on('tool/beforeExecute', (data) => {
  const policy = getApprovalPolicy(data.tool)
  if (policy === 'deny') {
    return { denied: true, reason: `${data.tool} is denied by policy` }
  }
  if (policy === 'ask') {
    return { pending: true, requiresApproval: true }
  }
  // إعادة undefined → لا تعترض، استمر في الانتشار
})

// إضافة Sandbox (بعد الموافقة)
ctx.on('tool/beforeExecute', (data) => {
  if (!isInSandbox(data.params.cwd)) {
    return { denied: true, reason: 'execution outside sandbox' }
  }
})

const result = ctx.bail('tool/beforeExecute', data)
if (result) {
  // عُترض
  ctx.logger.warn('tool execution denied:', result.reason)
} else {
  // لم يُعترض، يمكن التنفيذ
  await executeTool(data)
}

ctx.on('session/initialized', async (data) => {
  await loadUserPreferences(data.userId)
})

ctx.on('session/initialized', async (data) => {
  await setupWorkspace(data.workspaceId)
})

ctx.on('session/initialized', async (data) => {
  await warmCache(data.projectPath)
})

// ثلاثة مستمعين يُنفذون بالتسلسل
await ctx.serial('session/initialized', { userId: 'alice', workspaceId: 'ws-1' })

// emit: متوازي (لا ينتظر)
ctx.emit('session/created', data)   // لا ينتظر اكتمال المستمعين

// serial: متسلسل (ينتظر)
await ctx.serial('session/created', data)  // ينتظر اكتمال جميع المستمعين

ctx.on('message/format', async (data, next) => {
  data.text = data.text.trim()
  return next(data)
})

ctx.on('message/format', async (data, next) => {
  data.text = data.text.replace(/\s+/g, ' ')
  return next(data)
})

ctx.on('message/format', async (data, next) => {
  data.text = data.text.substring(0, 4096)
  return next(data)
})

const result = await ctx.waterfall('message/format', { text: '  hello   world  ' })
// result.text === 'hello world' (trim → collapse → truncate)

ctx.on('event/name', async (data, next) => {
  // تعديل البيانات
  data.field = newValue
  
  // استدعاء next للتمرير للمستمع التالي
  return next(data)
  
  // عدم استدعاء next → السلسلة مُقطعة، البيانات لا تُمرر أبعد
})

ctx.on('request/process', async (data, next) => {
  if (!data.authenticated) {
    return { error: 'unauthenticated' }  // لا تستدعي next، السلسلة مُقطعة
  }
  return next(data)
})

session/created        → نطاق الجلسة
session/destroyed      → نطاق الجلسة
tool/beforeExecute     → نطاق الأدوات (نطاق فرعي للقدرات)
tool/afterExecute      → نطاق الأدوات
agent/initialized      → نطاق الوكيل
llm/request            → نطاق LLM

// اشترك في جميع أحداث نطاق الأدوات
ctx.on('tool/*', (eventName, data) => {
  ctx.logger.info(`tool event: ${eventName}`)
})

// events.ts
interface MyPluginEvents {
  'my-plugin/data-loaded': { source: string; count: number }
  'my-plugin/data-error': { source: string; error: Error }
}

declare module '@deepseek-ai/cordis' {
  interface Events extends MyPluginEvents {}
}

ctx.emit('my-plugin/data-loaded', { source: 'api', count: 42 })  // ✅ نوع صحيح
ctx.emit('my-plugin/data-loaded', { wrong: true })                // ❌ خطأ نوع

ctx.on('my-plugin/data-loaded', (data) => {
  // data يُستنتج تلقائياً كـ { source: string; count: number }
  ctx.logger.info(`loaded ${data.count} items from ${data.source}`)
})

// أحداث داخلية للإضافة
interface InternalEvents {
  'cache/hit': { key: string; age: number }
  'cache/miss': { key: string }
  'cache/evicted': { key: string; reason: string }
}

// توسيع واجهة Events العامة
declare module '@deepseek-ai/cordis' {
  interface Events extends InternalEvents {}
}

// تصدير لاستخدامه بإضافات أخرى
export type CacheEvents = InternalEvents

{نطاق}/{فعل-ماضي}    ✅ session/created
{نطاق}/{فعل-مضارع}    ✅ tool/execute (قيد التنفيذ)
{نطاق}/before{فعل}    ✅ tool/beforeExecute (خطاف قبلي)
{نطاق}/after{فعل}     ✅ tool/afterExecute (خطاف بعدي)
{نطاق}/{اسم-حالة}     ✅ fiber/errored (حالة)