@chorus-aidlc/chorus-openclaw-plugin 0.4.0 → 0.5.3

package/dist/wake.js

@@ -0,0 +1,234 @@
+/**
+ * Wake mechanism for the Chorus plugin.
+ *
+ * Runs an agent turn IN-PROCESS with the wake text as the agent's prompt, via
+ * `api.runtime.agent.runEmbeddedAgent(...)` — the same primitive the cron
+ * service uses to "run the agent now with this prompt"
+ * (`../openclaw/src/cron/isolated-agent/run-executor.ts:266`).
+ *
+ * WHY NOT enqueueSystemEvent + heartbeat: that path was tried and does NOT
+ * deliver our text. `enqueueSystemEvent` only pushes onto the session queue,
+ * and the heartbeat prompt builder only renders exec-completion / cron events
+ * into a prompt (`../openclaw/src/infra/heartbeat-runner.ts:1240-1252`); a plain
+ * notification event is never injected, so the agent turned on the generic
+ * `[OpenClaw heartbeat poll]` prompt with no Chorus content. runEmbeddedAgent
+ * delivers the prompt directly and runs a real turn that can call the MCP tools.
+ *
+ * The runtime surface used here is declared on `PluginRuntimeCore.agent` in
+ * `../openclaw/src/plugins/runtime/types-core.ts:180-221`. The local SDK shim
+ * types `api.runtime` permissively, so we narrow the slice we use inline —
+ * mirroring `mcp-registration.ts` (api.runtime.config). Verified signatures:
+ *   - runEmbeddedAgent(RunEmbeddedAgentParams) — required: sessionId,
+ *     sessionFile, workspaceDir, prompt, timeoutMs, runId (params.ts:39+).
+ *   - agent.session.getSessionEntry({ sessionKey, agentId }) → SessionEntry?
+ *     (store.ts:210); SessionEntry has sessionId + optional sessionFile.
+ *   - agent.session.resolveSessionFilePath(sessionId, { sessionFile }, { agentId })
+ *     (paths.ts:267).
+ *   - agent.resolveAgentWorkspaceDir(cfg, agentId) / resolveAgentDir(cfg, agentId)
+ *     — positional (agent-scope-config.ts:170/195).
+ *   - agent.resolveAgentTimeoutMs({ cfg }) → number (timeout.ts:15).
+ */
+const FALLBACK_DEFAULT_AGENT_ID = "main";
+const DEFAULT_MAIN_KEY = "main";
+/** Mirror of OpenClaw's `normalizeAgentId` lowercasing fallback. */
+function normalizeAgentId(value) {
+    const trimmed = (value ?? "").trim().toLowerCase();
+    if (!trimmed)
+        return FALLBACK_DEFAULT_AGENT_ID;
+    // Keep it path-safe + shell-friendly (matches openclaw VALID_ID_RE behavior).
+    if (/^[a-z0-9][a-z0-9_-]{0,63}$/.test(trimmed))
+        return trimmed;
+    const collapsed = trimmed
+        .replace(/[^a-z0-9_-]+/g, "-")
+        .replace(/^-+/, "")
+        .replace(/-+$/, "")
+        .slice(0, 64);
+    return collapsed || FALLBACK_DEFAULT_AGENT_ID;
+}
+/** Mirror of OpenClaw's `normalizeMainKey`. */
+function normalizeMainKey(value) {
+    const trimmed = (value ?? "").trim().toLowerCase();
+    return trimmed || DEFAULT_MAIN_KEY;
+}
+/**
+ * Resolve the main agent session key from the host config.
+ *
+ * This faithfully replicates OpenClaw's `resolveMainSessionKey(cfg)`
+ * (`../openclaw/src/config/sessions/main-session.ts:14`): a background plugin
+ * has no inbound message route to derive a session key from, so the wake must
+ * target the main agent's session. We cannot import the OpenClaw internal here
+ * (the resolvable `openclaw` peer is an older build), so we re-derive the key
+ * from `api.config` (the live `OpenClawConfig` snapshot) using the same rules:
+ *
+ *   - `session.scope === "global"`  → the literal `"global"` queue
+ *   - otherwise → `agent:<defaultAgentId>:<mainKey>`, where defaultAgentId is
+ *     the agent flagged `default`, else the first listed agent, else "main".
+ *
+ * Returns `null` when no session key can be resolved. The design's no-session
+ * fallback (graceful drop) then applies — we never fabricate a session.
+ */
+export function resolveSessionKey(api) {
+    const cfg = api.config;
+    if (!cfg)
+        return null;
+    if (cfg.session?.scope === "global") {
+        return "global";
+    }
+    const agents = Array.isArray(cfg.agents?.list) ? cfg.agents.list : [];
+    const defaultAgentId = agents.find((agent) => agent?.default)?.id ?? agents[0]?.id ?? FALLBACK_DEFAULT_AGENT_ID;
+    const key = `agent:${normalizeAgentId(defaultAgentId)}:${normalizeMainKey(cfg.session?.mainKey)}`;
+    return key || null;
+}
+/**
+ * Resolve the default agent id (matches OpenClaw's `resolveDefaultAgentId`):
+ * the agent flagged `default`, else the first listed agent, else "main".
+ * runEmbeddedAgent and the session/workspace resolvers are all agent-scoped.
+ */
+export function resolveAgentId(api) {
+    const cfg = api.config;
+    const agents = Array.isArray(cfg?.agents?.list) ? cfg.agents.list : [];
+    const id = agents.find((a) => a?.default)?.id ?? agents[0]?.id ?? FALLBACK_DEFAULT_AGENT_ID;
+    return normalizeAgentId(id);
+}
+/**
+ * Resolve the configured default model into `{ provider, model }` so we can pass
+ * them explicitly to runEmbeddedAgent. WHY THIS IS REQUIRED: runEmbeddedAgent
+ * does NOT auto-resolve the model from config when `provider`/`model` are
+ * omitted — it falls back to the built-in `DEFAULT_MODEL` ("gpt-5.5",
+ * `../openclaw/src/agents/defaults.ts:4`), which fails with "Unknown model"
+ * unless that happens to be configured. The host's own resolver
+ * (`resolveConfiguredModelRef`, `../openclaw/src/agents/model-selection-shared.ts`)
+ * is NOT exposed to plugins, so we mirror its primary-ref read: `agents.defaults.model`
+ * is either a bare `"provider/model"` string or `{ primary: "provider/model" }`
+ * (`resolvePrimaryStringValue`), split on the first "/".
+ *
+ * Returns null when no default model is configured (then we omit the overrides
+ * and let the host fall back — same as before, but at least we tried).
+ */
+export function resolveModelRef(api) {
+    const model = api.config
+        ?.agents?.defaults?.model;
+    const raw = typeof model === "string"
+        ? model
+        : model && typeof model === "object"
+            ? model.primary
+            : undefined;
+    const ref = typeof raw === "string" ? raw.trim() : "";
+    const slash = ref.indexOf("/");
+    if (slash <= 0 || slash >= ref.length - 1) {
+        return null;
+    }
+    return { provider: ref.slice(0, slash), model: ref.slice(slash + 1) };
+}
+function getRuntimeAgent(api) {
+    const agent = api.runtime?.agent;
+    if (!agent ||
+        typeof agent.runEmbeddedAgent !== "function" ||
+        typeof agent.resolveAgentWorkspaceDir !== "function" ||
+        typeof agent.resolveAgentTimeoutMs !== "function" ||
+        typeof agent.session?.getSessionEntry !== "function" ||
+        typeof agent.session?.resolveSessionFilePath !== "function") {
+        return null;
+    }
+    return agent;
+}
+/**
+ * Build a stable-ish unique id without Date.now()/Math.random() (some hosts
+ * sandbox those). A monotonic counter + the contextKey is enough for runId
+ * uniqueness within a process.
+ */
+let wakeCounter = 0;
+function nextRunId(contextKey) {
+    wakeCounter += 1;
+    return `chorus-wake-${wakeCounter}-${contextKey}`;
+}
+/**
+ * Build a `wake(message, contextKey)` callback bound to the host runtime.
+ *
+ * Each wake resolves the main agent's session + workspace and runs an agent
+ * turn IN-PROCESS with `message` as the prompt (via runEmbeddedAgent). The turn
+ * has the agent's normal tool set (including the `chorus__*` MCP tools), so the
+ * agent can read the entity, the comment thread, and post back to Chorus.
+ *
+ * Failure modes (never throw — the SSE service must stay alive):
+ *   - no resolvable session key / agent runtime unavailable → log + drop;
+ *   - no existing session entry → run with a fresh sessionId (the runner
+ *     creates the transcript); the agent starts a new conversation;
+ *   - runEmbeddedAgent rejects (e.g. a turn is already in flight) → log + drop
+ *     (the next SSE event re-triggers).
+ *
+ * Runs are fire-and-forget (the SSE dispatch path is sync); we log completion.
+ */
+export function createWake(api, logger) {
+    return (message, contextKey) => {
+        const sessionKey = resolveSessionKey(api);
+        if (!sessionKey) {
+            logger.warn(`[Chorus] Wake DROPPED — could not resolve a main agent session key (contextKey=${contextKey}). Event: ${message.slice(0, 100)}`);
+            return;
+        }
+        const agent = getRuntimeAgent(api);
+        if (!agent) {
+            logger.warn(`[Chorus] Wake DROPPED — api.runtime.agent.runEmbeddedAgent (or a required session helper) is unavailable on this host (contextKey=${contextKey}).`);
+            return;
+        }
+        const cfg = api.config;
+        const agentId = resolveAgentId(api);
+        // Resolve the EXISTING main-agent session so the wake turn continues the
+        // real conversation (context + MCP tools). If none exists yet, fall back to
+        // a fresh session id — runEmbeddedAgent creates the transcript file.
+        let sessionId;
+        let sessionFile;
+        try {
+            const entry = agent.session.getSessionEntry({ sessionKey, agentId });
+            sessionId = entry?.sessionId ?? nextRunId(contextKey);
+            sessionFile = agent.session.resolveSessionFilePath(sessionId, entry?.sessionFile ? { sessionFile: entry.sessionFile } : undefined, { agentId });
+        }
+        catch (err) {
+            logger.warn(`[Chorus] Wake DROPPED — session resolution failed (contextKey=${contextKey}): ${err}`);
+            return;
+        }
+        let workspaceDir;
+        let agentDir;
+        let timeoutMs;
+        try {
+            workspaceDir = agent.resolveAgentWorkspaceDir(cfg, agentId);
+            agentDir = agent.resolveAgentDir(cfg, agentId);
+            timeoutMs = agent.resolveAgentTimeoutMs({ cfg });
+        }
+        catch (err) {
+            logger.warn(`[Chorus] Wake DROPPED — workspace/timeout resolution failed (contextKey=${contextKey}): ${err}`);
+            return;
+        }
+        // Resolve the configured model; runEmbeddedAgent otherwise falls back to the
+        // built-in DEFAULT_MODEL ("gpt-5.5") and fails with "Unknown model".
+        const modelRef = resolveModelRef(api);
+        if (!modelRef) {
+            logger.warn(`[Chorus] No agents.defaults.model configured — wake turn will use the host default model, which may be unavailable (contextKey=${contextKey}).`);
+        }
+        const runId = nextRunId(contextKey);
+        logger.info(`[Chorus] Waking agent via embedded run (sessionKey=${sessionKey}, model=${modelRef ? `${modelRef.provider}/${modelRef.model}` : "host-default"}, contextKey=${contextKey})`);
+        // Fire-and-forget: the SSE dispatch path is synchronous, and a wake turn
+        // can take many seconds. We log completion/failure but never await here.
+        // `disableMessageTool: true` → headless turn; the agent acts via MCP tools
+        // (chorus_add_comment, etc.) rather than replying to a chat channel.
+        void Promise.resolve()
+            .then(() => agent.runEmbeddedAgent({
+            sessionId,
+            sessionKey,
+            agentId,
+            trigger: "manual",
+            sessionFile,
+            ...(agentDir ? { agentDir } : {}),
+            workspaceDir,
+            config: cfg,
+            prompt: message,
+            timeoutMs,
+            runId,
+            disableMessageTool: true,
+            ...(modelRef ? { provider: modelRef.provider, model: modelRef.model } : {}),
+        }))
+            .then(() => logger.info(`[Chorus] Wake turn completed (sessionKey=${sessionKey}, contextKey=${contextKey})`))
+            .catch((err) => logger.warn(`[Chorus] Wake turn failed (sessionKey=${sessionKey}, contextKey=${contextKey}): ${err instanceof Error ? err.message : String(err)}`));
+    };
+}
+//# sourceMappingURL=wake.js.map

package/dist/wake.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wake.js","sourceRoot":"","sources":["../src/wake.ts"],"names":[],"mappings":"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"}

package/openclaw.plugin.json

@@ -1,28 +1,29 @@
 {
   "id": "chorus-openclaw-plugin",
+  "name": "Chorus",
+  "description": "Chorus AI-DLC collaboration platform — native MCP + SSE real-time events",
   "skills": ["./skills"],
+  "activation": {
+    "onStartup": true
+  },
+  "uiHints": {
+    "apiKey": {
+      "label": "Chorus API Key",
+      "placeholder": "cho_...",
+      "sensitive": true
+    }
+  },
   "configSchema": {
     "type": "object",
     "additionalProperties": false,
     "properties": {
       "chorusUrl": {
         "type": "string",
-        "description": "Chorus server URL"
+        "description": "Chorus server URL (e.g. https://chorus.example.com)"
       },
       "apiKey": {
         "type": "string",
         "description": "Chorus API Key (cho_ prefix)"
-      },
-      "projectUuids": {
-        "type": "array",
-        "items": { "type": "string" },
-        "default": [],
-        "description": "Project UUIDs to monitor (empty = all)"
-      },
-      "autoStart": {
-        "type": "boolean",
-        "default": true,
-        "description": "Auto-claim tasks on assignment"
       }
     }
   }

package/package.json

@@ -1,12 +1,18 @@
 {
   "name": "@chorus-aidlc/chorus-openclaw-plugin",
-  "version": "0.4.0",
-  "description": "OpenClaw plugin for Chorus AI-DLC collaboration platform — SSE real-time events + MCP tool integration",
+  "version": "0.5.3",
+  "description": "OpenClaw plugin for Chorus AI-DLC collaboration platform — native MCP + SSE real-time events",
   "license": "MIT",
   "type": "module",
   "main": "src/index.ts",
   "scripts": {
-    "typecheck": "tsc --noEmit"
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "clean": "rm -rf dist",
+    "release": "bash bin/publish.sh",
+    "prepublishOnly": "npm run clean && npm run typecheck && npm run test && npm run build"
   },
   "peerDependencies": {
     "openclaw": ">=2026.0.0"
@@ -16,10 +22,20 @@
     "zod": "^3.23.0"
   },
   "devDependencies": {
-    "typescript": "^5.9.0"
+    "typescript": "^5.9.0",
+    "vitest": "^3.2.0"
   },
   "openclaw": {
-    "extensions": ["src/index.ts"]
+    "extensions": ["./src/index.ts"],
+    "runtimeExtensions": ["./dist/index.js"],
+    "install": {
+      "npmSpec": "@chorus-aidlc/chorus-openclaw-plugin",
+      "defaultChoice": "npm",
+      "minHostVersion": ">=2026.4.27"
+    },
+    "compat": {
+      "pluginApi": ">=2026.4.27"
+    }
   },
   "repository": {
     "type": "git",
@@ -30,6 +46,8 @@
   "keywords": ["openclaw", "chorus", "ai-dlc", "mcp", "plugin", "agent"],
   "files": [
     "src",
+    "!src/**/__tests__",
+    "dist",
     "skills",
     "openclaw.plugin.json",
     "README.md"

package/skills/brainstorm/SKILL.md

@@ -0,0 +1,163 @@
+---
+name: brainstorm
+description: Optional divergent-then-convergent dialogue for fuzzy ideas. Invoked from the idea skill as a prelude to structured elaboration; produces one ElaborationRound of decision-point Q&A and returns control. Never writes files, never posts comments, never validates elaboration.
+license: AGPL-3.0
+metadata:
+  author: chorus
+  version: "0.9.4"
+  category: project-management
+  mcp_server: chorus
+---
+
+# Brainstorm Skill
+
+A divergent-then-convergent dialogue cadence for ideas whose direction is still being formed. Compresses the conversation into one `ElaborationRound` of decision-point Q&A — same shape as a structured elaboration round, but the questions, options and answers are synthesized at the end of the conversation rather than asked up front.
+
+This skill is a **producer** of one elaboration round; the **scheduler** decision (validate vs. follow-up) belongs to the calling idea skill.
+
+> **Tool namespace:** Chorus tools are exposed by the connected MCP server under a `chorus__` prefix on OpenClaw (e.g. `chorus__chorus_get_idea`). Bare names are used below for readability — prepend `chorus__` when invoking. See `/chorus` for the full rule.
+
+> **OpenClaw interaction model:** OpenClaw has no `AskUserQuestion` primitive. Every "ask the user" step below is a **plain-text prompt** — write the question (and options) in your message and wait for the user's free-text reply before continuing. The one-question-at-a-time cadence still holds: send one question, read the answer, then send the next.
+
+---
+
+## When invoked
+
+Only as a sub-step of the idea skill, only after the user has explicitly opted in (via the idea skill's plain-text Brainstorm prompt). Never run standalone, never run without user opt-in. The expected entry point is the idea skill's "Step 4.5: Brainstorm Mode (Optional Prelude)" — see the idea skill for the surrounding flow.
+
+---
+
+## Hard rules
+
+1. **One question at a time.** Each prompt MUST contain exactly one question. Wait for the user's reply before asking the next.
+2. **Multi-choice preferred.** Frame each question as 2-4 options where possible (offer them as a lettered list in your plain-text prompt). Open-ended is acceptable when options would be premature, but lean toward concrete choices.
+3. **Propose 2-3 directions before stopping divergence.** Once the requirement direction is clear enough to enumerate, present 2-3 distinct approaches in a single prompt. Mark exactly one as the recommended option and say why (the dominant tradeoff).
+4. **Explicit user approval required to exit divergence.** Do NOT proceed to synthesis until the user has selected one of the proposed directions in their reply.
+5. **No files written.** Do NOT write any markdown, design doc, scratch file, or any other file to disk. The conversation produces an `ElaborationRound` and nothing else on disk.
+6. **No comments posted.** Do NOT call `chorus_add_comment` from this skill. Comments belong to the idea skill or the user, not to the brainstorm step.
+7. **No design-doc handoff.** Do NOT invoke `writing-plans`, `writing-skills`, or any skill whose purpose is to produce a design document. The brainstorm output is the synthesized round — there is no separate doc.
+8. **No `validate_elaboration` call.** Do NOT call `chorus_pm_validate_elaboration` from this skill. Whether to resolve the elaboration or open a follow-up round (`chorus_pm_start_elaboration` again) is the calling idea skill's decision, not this skill's.
+
+---
+
+## Step-by-step
+
+### 1. Gather context
+
+Before asking the first divergent question, read the idea and surrounding project state. Mirror the idea skill's gather-context list:
+
+```
+chorus_get_idea({ ideaUuid })
+chorus_get_documents({ projectUuid })
+chorus_get_document({ documentUuid })   # for any document worth reading in full
+chorus_get_proposals({ projectUuid, status: "approved" })   # to understand patterns
+chorus_list_tasks({ projectUuid })   # to avoid duplicating existing work
+chorus_get_comments({ targetType: "idea", targetUuid: ideaUuid })
+```
+
+Skim each result for: stated background, stated requirements, stated constraints, and what is conspicuously NOT stated. The gaps are the questions worth asking.
+
+### 2. Divergent Q&A
+
+Ask one question at a time as a plain-text prompt. Aim to surface:
+
+- The **goal** the idea is trying to serve (often more abstract than the idea statement).
+- The **constraints** that exclude entire branches of solution space (deadlines, compatibility, scope).
+- The **success criteria** — how will the user know this is done.
+
+Keep each question single-purpose. If you need to ask three things, that is three prompts, not one combined message.
+
+### 3. Propose 2-3 directions
+
+When the goal, constraints, and success criteria are clear enough that you can name distinct approaches, present them in a single plain-text prompt:
+
+```
+Based on what you've told me, here are three directions. Which do you want? (reply A / B / C, or describe your own)
+
+A) <Option A — RECOMMENDED> — <what + tradeoff>
+B) <Option B> — <what + tradeoff>
+C) <Option C> — <what + tradeoff>
+
+I recommend A because <one sentence about the dominant tradeoff>.
+```
+
+State **why** you recommend one option — usually a sentence about the dominant tradeoff.
+
+### 4. Wait for explicit approval
+
+Do not proceed to synthesis if the user has not selected one of the options in their reply. If the user picks "Other" with free text, treat that as a new constraint — go back to step 2 or step 3 with the refined direction.
+
+### 5. Synthesize decision-point Q&A
+
+For each material decision the user made during the conversation, build one `ElaborationQuestion`. A "material decision" is a moment where the user chose between alternatives or set scope explicitly. Map each decision per the synthesis spec below.
+
+### 6. Persist the round
+
+Call `chorus_pm_start_elaboration` with the synthesized questions:
+
+```
+chorus_pm_start_elaboration({
+  ideaUuid,
+  depth: "standard",
+  questions: [
+    { id: "q1", text: "...", category: "...", options: [...] },
+    ...
+  ]
+})
+```
+
+Then submit the answers in one call:
+
+```
+chorus_answer_elaboration({
+  ideaUuid,
+  roundUuid,
+  answers: [
+    { questionId: "q1", selectedOptionId: "...", customText: "<rationale>" },
+    ...
+  ]
+})
+```
+
+### 7. Return control
+
+Stop here. Do **NOT** call `chorus_pm_validate_elaboration`. The idea skill's caller now decides:
+
+- If the synthesized round answers cover everything → caller obtains human confirmation, then resolves with `chorus_pm_validate_elaboration`.
+- If gaps remain → caller opens a structured Round 2 with `chorus_pm_start_elaboration`.
+
+The depth of any follow-up round is the caller's call, not yours.
+
+---
+
+## Synthesis spec
+
+Each material decision becomes exactly one `ElaborationQuestion` with these fields:
+
+| Field | Source |
+|---|---|
+| `text` | The decision question, phrased neutrally. Example: "Which depth-model placement?" |
+| `category` | `functional`, `non_functional`, `business_context`, `technical_context`, `user_scenario`, or `scope` — derived from the topic. |
+| `options` | All directions that were considered, length 2-5. Collapse near-duplicates into one option. |
+| `selectedOptionId` | The id of the option the user approved. |
+| `customText` | A 1-3 sentence rationale capturing the constraint or tradeoff that drove the choice. Not a transcript dump. |
+
+Rules:
+
+- A `customText` longer than ~3 sentences is a sign you are summarizing transcript instead of capturing rationale. Cut.
+- An `options` array of length 2 with binary "yes / no" framing is a sign you pre-narrowed alternatives. Re-examine — there are usually at least three meaningfully different paths, even if two of them get rejected quickly.
+- Skip "decisions" that were never genuinely contested. If the user agreed instantly to the only proposal, that is information for the idea content, not a decision-point Q&A.
+
+---
+
+## Anti-patterns
+
+Do not do any of the following. Each has a specific failure mode that this skill must prevent:
+
+- **Single-summary `customText` blob.** Compressing the entire conversation into one ElaborationQuestion with a long markdown summary in `customText`. The schema is multi-question for a reason — preserve the decision granularity.
+- **Transcript-as-comment.** Posting the raw conversation log as a comment on the idea (or anywhere). The synthesized round IS the artifact. Raw transcripts pollute the audit trail with noise.
+- **File writes.** Writing any markdown, design doc, plan, or scratch file to disk. There is no design doc in this flow. This is a deliberate divergence from the upstream `superpowers/brainstorming` cadence.
+- **`validate_elaboration` calls.** Closing the elaboration phase from this skill. The lifecycle decision belongs to the idea skill. Calling it here strips the caller of its scheduler role.
+- **`writing-plans` / design-doc handoff.** Invoking any skill that produces an implementation plan or design document. The Chorus pipeline already has Proposal → Document Drafts → Task Drafts for that — the brainstorm output feeds them through ElaborationRound, not through external doc skills.
+- **Length-2 binary "yes / no" framings.** Reducing every decision to "do this thing — yes / no". Almost always the genuine alternatives are 3+ approaches with meaningfully different tradeoffs. Length-2 framings often mean the divergent phase ended too early.
+- **Asking multiple questions in one prompt.** The cadence is one question per turn during divergence, then one final convergence prompt with 2-3 options. Combining unrelated questions is a sign you are rushing.