Plugin रनटाइम सहायक सुविधाएँ

// एजेंट की कार्यशील डायरेक्टरी रिज़ॉल्व करें (agentId आवश्यक है)
const agentDir = api.runtime.agent.resolveAgentDir(cfg, agentId);

// एजेंट वर्कस्पेस रिज़ॉल्व करें
const workspaceDir = api.runtime.agent.resolveAgentWorkspaceDir(cfg, agentId);

// एजेंट की पहचान प्राप्त करें
const identity = api.runtime.agent.resolveAgentIdentity(cfg);

// डिफ़ॉल्ट चिंतन स्तर प्राप्त करें
const thinking = api.runtime.agent.resolveThinkingDefault({
  cfg,
  provider,
  model,
});

// उपयोगकर्ता द्वारा दिए गए चिंतन स्तर को सक्रिय प्रोवाइडर प्रोफ़ाइल के विरुद्ध सत्यापित करें
const policy = api.runtime.agent.resolveThinkingPolicy({ provider, model });
const level = api.runtime.agent.normalizeThinkingLevel("extra high");
if (level && policy.levels.some((entry) => entry.id === level)) {
  // स्तर को एम्बेड किए गए रन में पास करें
}

// एजेंट टाइमआउट प्राप्त करें
const timeoutMs = api.runtime.agent.resolveAgentTimeoutMs(cfg);

// सुनिश्चित करें कि वर्कस्पेस मौजूद है
await api.runtime.agent.ensureAgentWorkspace(cfg);

// एम्बेड किया हुआ एजेंट टर्न चलाएँ
const result = await api.runtime.agent.runEmbeddedAgent({
  sessionId: "my-plugin:task-1",
  runId: crypto.randomUUID(),
  workspaceDir: api.runtime.agent.resolveAgentWorkspaceDir(cfg, agentId),
  prompt: "नवीनतम परिवर्तनों का सारांश दें",
  timeoutMs: api.runtime.agent.resolveAgentTimeoutMs(cfg),
});

const entry = api.runtime.agent.session.getSessionEntry({ agentId, sessionKey });
for (const { sessionKey, entry } of api.runtime.agent.session.listSessionEntries({ agentId })) {
  // पुराने sessions.json आकार पर निर्भर हुए बिना सत्र पंक्तियों पर इटरेट करें।
}
await api.runtime.agent.session.patchSessionEntry({
  agentId,
  sessionKey,
  update: (entry) => ({ thinkingLevel: "high" }),
});

const created = await api.runtime.agent.session.createSessionEntry({
  cfg,
  key: "agent:main:my-plugin:task-1",
  initialEntry: {
    agentHarnessId: "my-harness",
    modelSelectionLocked: true,
    pluginExtensions: { "my-plugin": { phase: "initializing" } },
  },
  afterCreate: async () => ({
    pluginExtensions: { "my-plugin": { phase: "ready" } },
  }),
});

const storePath = api.runtime.agent.session.resolveStorePath(cfg.session?.store, { agentId });
await api.runtime.agent.session.runWithWorkAdmission(
  { storePath, sessionKey },
  async (signal) => {
    // सत्र बनाएँ या अपडेट करें, फिर signal को स्वीकृत एजेंट रन में पास करें।
  },
);

const model = api.runtime.agent.defaults.model; // उदाहरण: "gpt-5.6-sol"
const provider = api.runtime.agent.defaults.provider; // उदाहरण: "openai"

const result = await api.runtime.llm.complete({
  messages: [{ role: "user", content: "इस ट्रांसक्रिप्ट का सारांश प्रस्तुत करें।" }],
  purpose: "my-plugin.summary",
  maxTokens: 512,
  temperature: 0.2,
  reasoning: "high",
});

const lease = await api.runtime.llm.acquireLocalService(
  {
    providerId,
    baseUrl,
    headers,
  },
  signal,
);
try {
  // प्रदाता अनुरोध भेजें और उसका पूरी तरह उपयोग करें।
} finally {
  await lease?.release();
}

if (await api.runtime.gateway.isAvailable()) {
  const result = await api.runtime.gateway.request<{ callId: string }>(
    "voicecall.start",
    { to: "+15550001234", mode: "conversation" },
    { timeoutMs: 60_000 },
  );
}

// सबएजेंट रन शुरू करें
const { runId } = await api.runtime.subagent.run({
  sessionKey: "agent:main:subagent:search-helper",
  message: "इस क्वेरी को केंद्रित अनुवर्ती खोजों में विस्तृत करें।",
  toolsAlsoAllow: ["my_plugin_progress"],
  provider: "openai", // वैकल्पिक ओवरराइड
  model: "gpt-5.6-sol", // वैकल्पिक ओवरराइड
  deliver: false,
});

// पूर्ण होने की प्रतीक्षा करें
const result = await api.runtime.subagent.waitForRun({ runId, timeoutMs: 30000 });

// सत्र संदेश पढ़ें
const { messages } = await api.runtime.subagent.getSessionMessages({
  sessionKey: "agent:main:subagent:search-helper",
  limit: 10,
});

// सत्र हटाएँ
await api.runtime.subagent.deleteSession({
  sessionKey: "agent:main:subagent:search-helper",
});

const authority = api.runtime.sandbox.resolveWorkspaceAuthority({
  config: cfg,
  agentId,
  sessionKey,
});

const liveAuthority = await api.runtime.sandbox.prepareWorkspaceAuthority({
  config: cfg,
  agentId,
  sessionKey,
  workspaceDir,
  confinedToolNames: ["my_plugin_safe_tool"],
});

const { nodes } = await api.runtime.nodes.list({ connected: true });

const result = await api.runtime.nodes.invoke({
  nodeId: "mac-studio",
  command: "my-plugin.command",
  params: { action: "start" },
  timeoutMs: 30000,
});

const taskFlow = api.runtime.tasks.managedFlows.fromToolContext(ctx);

const created = taskFlow.createManaged({
  controllerId: "my-plugin/review-batch",
  goal: "नए पुल रिक्वेस्ट की समीक्षा करें",
});

const child = taskFlow.runTask({
  flowId: created.flowId,
  runtime: "acp",
  childSessionKey: "agent:main:subagent:reviewer",
  task: "PR #123 की समीक्षा करें",
  status: "running",
  startedAt: Date.now(),
});

const waiting = taskFlow.setWaiting({
  flowId: created.flowId,
  expectedRevision: created.revision,
  currentStep: "await-human-reply",
  waitJson: { kind: "reply", channel: "telegram" },
});

// मानक TTS
const clip = await api.runtime.tts.textToSpeech({
  text: "OpenClaw की ओर से नमस्ते",
  cfg: api.config,
});

// टेलीफ़ोनी-अनुकूलित TTS
const telephonyClip = await api.runtime.tts.textToSpeechTelephony({
  text: "OpenClaw की ओर से नमस्ते",
  cfg: api.config,
});

// उपलब्ध आवाज़ों की सूची बनाएँ
const voices = await api.runtime.tts.listVoices({
  provider: "elevenlabs",
  cfg: api.config,
});

// किसी इमेज का वर्णन करें
const image = await api.runtime.mediaUnderstanding.describeImageFile({
  filePath: "/tmp/inbound-photo.jpg",
  cfg: api.config,
  agentDir: "/tmp/agent",
});

// ऑडियो का लिप्यंतरण करें
const { text } = await api.runtime.mediaUnderstanding.transcribeAudioFile({
  filePath: "/tmp/inbound-audio.ogg",
  cfg: api.config,
  mime: "audio/ogg", // वैकल्पिक, जब MIME का अनुमान नहीं लगाया जा सकता
});

// किसी वीडियो का वर्णन करें
const video = await api.runtime.mediaUnderstanding.describeVideoFile({
  filePath: "/tmp/inbound-video.mp4",
  cfg: api.config,
});

// सामान्य फ़ाइल विश्लेषण
const result = await api.runtime.mediaUnderstanding.runFile({
  filePath: "/tmp/inbound-file.pdf",
  cfg: api.config,
});

// किसी विशिष्ट प्रदाता/मॉडल के माध्यम से संरचित इमेज निष्कर्षण।
// कम-से-कम एक इमेज शामिल करें; टेक्स्ट इनपुट पूरक संदर्भ हैं।
const evidence = await api.runtime.mediaUnderstanding.extractStructuredWithModel({
  provider: "codex",
  model: "gpt-5.6-sol",
  input: [
    {
      type: "image",
      buffer: receiptImageBuffer,
      fileName: "receipt.png",
      mime: "image/png",
    },
    { type: "text", text: "हस्तलिखित नोट के बजाय मुद्रित कुल राशि को प्राथमिकता दें।" },
  ],
  instructions: "विक्रेता, कुल राशि और खोजने योग्य टैग निकालें।",
  schemaName: "receipt.evidence",
  jsonSchema: {
    type: "object",
    properties: {
      vendor: { type: "string" },
      total: { type: "number" },
      tags: { type: "array", items: { type: "string" } },
    },
    required: ["vendor", "total"],
  },
  cfg: api.config,
});

const result = await api.runtime.imageGeneration.generate({
  prompt: "सूर्यास्त को चित्रित करता हुआ एक रोबोट",
  cfg: api.config,
});

const providers = api.runtime.imageGeneration.listProviders({ cfg: api.config });

const result = await api.runtime.videoGeneration.generate({
  prompt: "सूर्योदय के समय समुद्रतट के ऊपर उड़ता हुआ ड्रोन शॉट",
  cfg: api.config,
});

const providers = api.runtime.videoGeneration.listProviders({ cfg: api.config });

const result = await api.runtime.musicGeneration.generate({
  prompt: "कोडिंग सेशन के लिए एक उत्साहपूर्ण लो-फ़ाई ट्रैक",
  cfg: api.config,
});

const providers = api.runtime.musicGeneration.listProviders({ cfg: api.config });

const providers = api.runtime.webSearch.listProviders({ config: api.config });

const result = await api.runtime.webSearch.search({
  config: api.config,
  args: { query: "OpenClaw Plugin SDK", count: 5 },
});

const webMedia = await api.runtime.media.loadWebMedia(url);
const mime = await api.runtime.media.detectMime(buffer);
const kind = api.runtime.media.mediaKindFromMime("image/jpeg"); // "इमेज"
const isVoice = api.runtime.media.isVoiceCompatibleAudio(filePath);
const metadata = await api.runtime.media.getImageMetadata(filePath);
const resized = await api.runtime.media.resizeToJpeg(buffer, { maxWidth: 800 });
const terminalQr = await api.runtime.media.renderQrTerminal("https://openclaw.ai");
const pngQr = await api.runtime.media.renderQrPngBase64("https://openclaw.ai", {
  scale: 6, // 1-12
  marginModules: 4, // 0-16
});
const pngQrDataUrl = await api.runtime.media.renderQrPngDataUrl("https://openclaw.ai");
const tmpRoot = resolvePreferredOpenClawTmpDir();
const pngQrFile = await api.runtime.media.writeQrPngTempFile("https://openclaw.ai", {
  tmpRoot,
  dirPrefix: "my-plugin-qr-",
  fileName: "qr.png",
});

const cfg = api.runtime.config.current();
await api.runtime.config.mutateConfigFile({
  afterWrite: { mode: "auto" },
  mutate(draft) {
    draft.plugins ??= {};
  },
});

await api.runtime.system.enqueueSystemEvent(event);
api.runtime.system.requestHeartbeat({
  source: "other",
  intent: "event",
  reason: "plugin-event",
});
api.runtime.system.requestHeartbeatNow({ reason: "plugin-event" }); // अप्रचलित संगतता उपनाम।
const heartbeatResult = await api.runtime.system.runHeartbeatOnce({
  reason: "plugin-triggered-check",
});
const output = await api.runtime.system.runCommandWithTimeout(cmd, args, opts);
const hint = api.runtime.system.formatNativeDependencyHint(pkg);

api.runtime.events.onAgentEvent((event) => {
  /* ... */
});
api.runtime.events.onSessionTranscriptUpdate((update) => {
  /* ... */
});

const verbose = api.runtime.logging.shouldLogVerbose();
const childLogger = api.runtime.logging.getChildLogger({ plugin: "my-plugin" }, { level: "debug" });

const auth = await api.runtime.modelAuth.getApiKeyForModel({ model, cfg });

// अनुरोध के लिए तैयार प्रमाणीकरण, जिसमें प्रदाता रनटाइम आदान-प्रदान शामिल हैं (जैसे OAuth रीफ़्रेश)
const runtimeAuth = await api.runtime.modelAuth.getRuntimeAuthForModel({ model, cfg });

const providerAuth = await api.runtime.modelAuth.resolveApiKeyForProvider({
  provider: "openai",
  cfg,
});

const stateDir = api.runtime.state.resolveStateDir(process.env);
const store = api.runtime.state.openKeyedStore<MyRecord>({
  namespace: "my-feature",
  maxEntries: 200,
  defaultTtlMs: 15 * 60_000,
});

await store.register("key-1", { value: "hello" });
const claimed = await store.registerIfAbsent("dedupe-key", { value: "first" });
const value = await store.lookup("key-1");
await store.deleteIf?.("key-1", (current) => current.value === "hello");
await store.consume("key-1");
await store.clear();

const blobs = api.runtime.state.openBlobStore<MyBlobMetadata>({
  namespace: "rendered-artifacts",
  maxEntries: 100,
  maxBytesPerEntry: 4 * 1024 * 1024,
  maxBytesPerNamespace: 64 * 1024 * 1024,
  defaultTtlMs: 15 * 60_000,
});
await blobs.register(
  "artifact-1",
  new TextEncoder().encode("binary or text payload"),
  { contentType: "text/plain" },
);
const blob = await blobs.lookup("artifact-1");

await api.runtime.state.withLease(
  {
    namespace: "my-feature",
    key: "writer",
    database: { scope: "agent", agentId },
    leaseMs: 5 * 60_000,
    waitMs: 30_000,
  },
  async ({ signal, assertOwned }) => {
    await runExternalWriter({ signal });
    assertOwned();
  },
);

const saved = await api.runtime.channel.media.saveRemoteMedia({
  url,
  subdir: "inbound",
  maxBytes,
  filePathHint: fileName,
});

const mentionMatch = api.runtime.channel.mentions.matchesMentionWithExplicit(text, {
  mentionRegexes,
  mentionPatterns,
});

const decision = api.runtime.channel.mentions.resolveInboundMentionDecision({
  facts: {
    canDetectMention: true,
    wasMentioned: mentionMatch.matched,
    implicitMentionKinds: api.runtime.channel.mentions.implicitMentionKindWhen(
      "reply_to_bot",
      isReplyToBot,
    ),
  },
  policy: {
    isGroup,
    requireMention,
    allowTextCommands,
    hasControlCommand,
    commandAuthorized,
  },
});