@poping/yome 0.0.2 → 0.0.4

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,11 @@
+Yome Agent
+Copyright 2024-2026 Whopus / Yome contributors
+
+This product includes software developed at Whopus (https://yome.work).
+
+Licensed under the Apache License, Version 2.0; see LICENSE for the
+full text.
+
+The Yome Agent is the open-source agent runtime + skill client for the
+Yome platform. It is the same binary published to npm as @poping/yome,
+and mirrored as github.com/Whopus/yome-agent.

package/README.md

@@ -1,54 +1,333 @@
-# Yome CLI
+<div align="center">
 
-AI coding agent in your terminal.
+<img src=".assets/yome-icon.png" width="120" alt="Yome" />
 
-## Install
+# YOME AGENT
+
+### The Empower Kernel
+
+*Agentic context, native skills, bash kernel.*
+*The open-source substrate that makes AI feel and know you.*
+
+[English](./README.md) · [简体中文](./README.zh-CN.md)
+
+</div>
+
+---
+
+Yome Agent is not yet another chat agent. It is the open-source substrate of [Yome](https://yome.work) — an **Empower Kernel** that weaves the LLM, your devices and your native apps into one runtime.
+
+The model is strong. It lives nowhere near your twelve context silos. Today you are the router between context and tool; 80% of your workday is spent shuffling, not creating. Yome Agent exists to take that routing job away from you — not by inventing one more tool, but by waking up the tools you already own.
+
+---
+
+## Quickstart
 
 ```bash
-npm install -g @sobers/yome
+# Install
+npm install -g @poping/yome
+
+# Configure (saved to ~/.yome/config.json)
+yome --key sk-... --base-url https://your.endpoint --model your-model
+
+# Run
+yome                              # interactive REPL
+yome "summarise package.json"     # one-shot
+
+# Install your first native skill (PowerPoint editor)
+yome skill install github:Whopus/yome-skill-ppt
+yome skill list
 ```
 
-Or run directly with npx:
+Once `yome` is running, type:
+
+```
+> Make a new ppt titled "Q3 Review" and save it to my Desktop
+```
+
+The model issues real `ppt new ~/Desktop/q3.pptx` → `ppt title 1 --text="Q3 Review"` → `ppt save` Bash commands. Microsoft PowerPoint opens on your desktop. The file lands on disk. That is the minimum loop of an Empower Kernel.
+
+---
+
+## The Three Engines
+
+Yome Agent is composed of three engines, each independent yet interlocking. Each is a piece of ground truth from the *Agentic Empower Intelligence* blueprint in the Yome business plan.
+
+---
+
+### 1. Agentic Contextual Engine
+
+> Context is not a static string. It is a *living continuum*.
+
+The agent loop must not live only in the 30 seconds after you press Enter. It should be always-on, never-forget, ambient. This is the dimension that separates Yome Agent from traditional chat-style coding agents.
+
+| Capability | Meaning |
+|---|---|
+| **Daemon** | Yome runs as an OS-level daemon, not a chat window. It watches your filesystem, calendar, IM signals, and long-running jobs in the background — and only surfaces when something matters. The agent loop never has to be re-spawned from scratch. |
+| **Live compaction** | Long sessions auto-compress history; tokens never overflow, memory never lost |
+| **Oncall** | The agent is event-driven, not prompt-driven. WeChat / Feishu / Slack / iMessage messages, calendar fires, build finishes, GPU spikes, *@you* mentions — Yome reacts to the world and pages you with a one-line summary + a draft response, instead of waiting for you to ask. |
+
+**Available today:**
 
 ```bash
-npx @sobers/yome
+yome thread list                                # list past sessions in cwd
+yome thread share <session-id> --skill=<slug>   # build redacted case bundle
+yome thread submit <bundle-dir> --skill=<slug>  # publish as PR (needs gh CLI)
 ```
 
-## Configuration
+Sessions, history compaction and case bundles ship today. Daemon and Oncall are next-up on the `next` branch.
+
+---
+
+### 2. Agentic Native Skill
+
+> The scarce capability is not "another prompt template" or "an MCP wrapper running in the cloud". It is **invoking the native apps already installed on your machine** and making them obey agent instructions.
+
+We call them **Native Skills**:
+
+| Type | Runs where | Does what | Example |
+|---|---|---|---|
+| **Prompt Skill** | LLM context window | Loads a markdown prompt template | code-review, web-research |
+| **MCP Server** | Remote process | Exposes JSON-RPC tools to the LLM | github MCP, filesystem MCP |
+| **Native Skill** *(Yome)* | Your own machine (macOS / Win / Linux) | Drives native apps via AppleScript / Win32 / DBus | ppt, xl, cal, mail, rem |
+
+**Install / manage:**
+
+```bash
+yome skill install github:Whopus/yome-skill-ppt
+yome skill perms @yome/ppt                      # view granted capabilities
+yome skill perms @yome/ppt --revoke=fs:write    # revoke one
+yome skill validate                             # lint the cwd skill
+yome skill publish                              # publish to hub (after `yome login`)
+```
+
+**Capability model.** Every skill must declare the OS resources it needs in its manifest, and the user must grant them explicitly at install time. This is not "asking for permission" in a prompt — it is a real sandbox gate:
+
+| Capability | Meaning |
+|---|---|
+| `applescript` | Execute AppleScript (macOS only) |
+| `fs:read` / `fs:write` / `fs:delete` | Filesystem access, scope-limited |
+| `network` | Outbound network |
+| `shell` | Arbitrary shell commands (dangerous, denied by default) |
+
+Ungranted capabilities return `capability not granted: …`. The model sees the error and asks you to grant — never silently fails.
+
+**Native skills available today:**
+
+| Skill | Domain | Status |
+|---|---|---|
+| `@yome/ppt` | `ppt` | **stable** — 16 actions, batch-ready, 4 themes (`--doc`) |
+| `@yome/xl` | `xl` | beta |
+| `@yome/cal` | `cal` | beta |
+| `@yome/rem` | `rem` | beta |
+| `@yome/mail` | `mail` | alpha |
+
+---
+
+### 3. Agentic Bash Kernel
+
+> Bash is the interface. A skill is a verb. **However a user types it in a shell, the model invokes it the same way through its Bash tool.** One syntax. Two users.
+
+The model does not have to learn a new tool:
+
+```jsonc
+// What the model sees in its tools list — just one Bash:
+{ "name": "Bash", "description": "Run a shell command." }
+
+// What the model emits when it wants to add a slide:
+Bash({ "command": "ppt slide.add" })
+
+// The kernel intercepts BEFORE /bin/sh sees it, routes to the
+// installed @yome/ppt skill, runs the AppleScript, returns the result.
+```
 
-### Environment Variables
+#### Three-layer skill docs · L1 / L2 / L3
+
+All the information the model needs to pick and use a skill lives in three layers, each optimised for tokens / latency:
+
+| Layer | Where | Who reads it | Size |
+|---|---|---|---|
+| **L1 — Index** | Lives in the system prompt | The model on every turn | 3 lines / ~60 tokens per skill |
+| **L2 — Signature** | Returned by `<domain> --help` | The model once it decides to use the skill | ~50 lines / ~250 tokens |
+| **L3 — Cookbook** | Returned by `<domain> --doc [name]` | The model when the task is non-trivial | KB of markdown |
+
+**L1 looks like this** — the actual block for the `ppt` skill in the system prompt:
+
+```
+ppt | when:    user wants to create / edit / export PowerPoint .pptx slides
+    | effects: opens Microsoft PowerPoint, writes files (first save to ~/Desktop may show OS dialog)
+    | start:   ppt --help
+```
+
+Just three fields, because that is all the LLM needs when picking a tool: **when to fire, what side effects, what to type first**. Authored by the skill maintainer in `yome-skill.json`:
+
+```jsonc
+"l1": {
+  "when":    "user wants to create / edit / export PowerPoint .pptx slides",
+  "entry":   "ppt --help",
+  "effects": "opens Microsoft PowerPoint, writes files"
+}
+```
+
+**L2 (`ppt --help`)** is the hand-written `SIGNATURE.md` — one action per line, defaults inlined; the LLM can grok every arg in one read:
+
+```
+ppt new [path] [--force]                       create blank presentation
+ppt open <path>                                open existing .pptx
+ppt save [--path=P] [--force]                  save (or save-as)
+ppt slides                                     TSV: index, title, shape count
+ppt slide.add [--index=N] [--layout=N]
+ppt title <slide> --text=<str>
+ppt addtext <slide> --text=<str>
+                       [--left=100 --top=200 --width=400 --height=50]
+                       [--size=N --bold --italic]
+                       [--color=red|#RRGGBB|R,G,B]
+                       [--align=left|center|right]
+ppt fmt <slide> --shape=<n> [--size=N --bold --italic --color --bg --align]
+ppt export --format=pdf|png|jpg --path=<file> [--force]
+…
+```
+
+**L3 (`ppt --doc`)** lists cookbook templates; `ppt --doc blue-white` returns the full body (palette, type scale, batch example). The skill maintainer authors them under `docs/*.md` with frontmatter:
+
+```yaml
+---
+name: blue-white
+label: Blue & White
+summary: Corporate navy on white — quarterly reviews, product launches, sales decks
+tags: [theme, business]
+---
+```
+
+#### Batch mode · 6× speedup
+
+Sequential tasks are the #1 performance killer in a CLI agent — each AppleScript invocation has a 200 ms cold-start. The Yome Bash kernel has a built-in `batch` verb that fuses N steps into one call, and `--merge` further fuses N scripts into a single `osascript` process:
 
 ```bash
-export YOME_BASE_URL=https://dashscope.aliyuncs.com/apps/anthropic
-export YOME_API_KEY=sk-
-export YOME_MODEL=qwen-plus
+ppt batch --merge <<EOF
+new ~/Desktop/q3.pptx
+title 1 --text="Q3 Review"
+slide.add
+title 2 --text="Revenue"
+addtext 2 --text="+18% YoY" --size=72 --bold --color=green --align=center
+slide.add
+title 3 --text="Conclusion"
+save
+export --format=pdf --path=~/Desktop/q3.pdf
+EOF
 ```
 
-| Variable | Description | Default |
+Measured numbers — 8 sequential `ppt` actions, M1 Mac:
+
+| Mode | Wall time | Speedup |
 |---|---|---|
-| `YOME_API_KEY` | API key | - |
-| `YOME_BASE_URL` | API base URL | `https://zenmux.ai/api` |
-| `YOME_MODEL` | Model name | - |
-| `YOME_PROVIDER` | API provider: `anthropic` or `openai` | auto-detected |
+| 8 separate `ppt …` calls | 2041 ms | 1× |
+| `ppt batch <<EOF…EOF` (sequential) | 2353 ms | 1× (parsing overhead) |
+| `ppt batch --merge <<EOF…EOF` | **334 ms** | **6.1×** |
 
-### CLI Flags
+The kernel decides at the token level: is the first token a reserved system command (47 of them: `git`, `ls`, `cd`, `rm`, `node`, …)? Yes → straight to `/bin/sh`. Else → is it the domain of an installed skill? Yes → route to the skill. No → pass through to shell.
+
+So *one Bash tool* simultaneously carries:
+
+- Real shell commands (`ls`, `git status`, `python script.py`)
+- Skill verbs (`ppt new`, `cal create`)
+- Shell composition (`ppt slides | head -3` — domain stdout piped to a real shell)
+- Batches (`ppt batch --merge <<EOF…EOF`)
+
+---
+
+## Skills Marketplace
 
 ```bash
-yome --key sk-xxx --base-url https://api.anthropic.com
-yome --model qwen-plus --provider openai
+yome skill search powerpoint              # search public hub
+yome skill install github:Whopus/yome-skill-ppt
+yome skill install ./my-local-skill       # local dir
+yome skill install github:owner/repo@v2   # pin to a ref
+yome skill update                         # re-pull all installed
+yome skill rollback @yome/ppt             # one-level undo
+yome skill enable / disable / link / unlink / doctor
 ```
 
-Flags will be saved to `~/.yome/config.json` for future use.
+`yome skill publish` publishes the cwd to the public hub (requires `yome login` via GitHub Device Flow). The hub is just a discovery layer; skills themselves remain plain git repos. No vendor lock-in.
+
+---
 
-## Usage
+## Configuration
 
 ```bash
-# Interactive mode
-yome
+export YOME_API_KEY=sk-...
+export YOME_BASE_URL=https://your.endpoint
+export YOME_MODEL=claude-opus-4-6
+export YOME_PROVIDER=anthropic     # or openai (auto-detected from base URL)
+```
+
+Or persist once into `~/.yome/config.json`:
+
+```bash
+yome --key sk-... --base-url https://… --model …
+```
 
-# With a prompt
-yome "help me read package.json"
+**Storage layout:**
 
-# Set config and run
-yome --key sk-xxx --base-url https://dashscope.aliyuncs.com/apps/anthropic
 ```
+~/.yome/
+├── config.json                   # API config
+├── skills/                       # installed native skills
+│   ├── .index.json               # cached registry
+│   └── yome/
+│       └── ppt/                  # the @yome/ppt skill, exactly the git repo
+└── threads/                      # session history (per cwd)
+```
+
+---
+
+## Philosophy
+
+> *Users will not learn a new product. Users will not change the way they already work.*
+
+We do not replace your tools. We **empower** them without interrupting the way you already work. Mail, Chat, Docs, Calendar, Files, Web — they already live on your machine. We just bolt on a living-context layer and wake them up.
+
+| Before | After |
+|---|---|
+| Passive Tool | Proactive Agent |
+| You route context → tool | Yome reaches into every device for you |
+| 12 contexts, 0 AI | 1 buddy that knows everything about you |
+
+---
+
+## Project Status
+
+| Area | Status |
+|---|---|
+| Bash kernel (tokenizer + dispatcher + permission gate) | **stable** |
+| Native skill format (yome-skill.json + L1/L2/L3 docs) | **stable** |
+| `@yome/ppt` (16 actions, batch + 4 themes) | **stable** |
+| Skill hub (search / install / publish) | **stable** |
+| Capability model (sandbox grants) | **stable** |
+| Thread history + case bundles | **stable** |
+| Live history compaction | beta |
+| Daemon (OS-level always-on loop) | experimental, on `next` branch |
+| Oncall (event-driven, auto-paging) | next-up |
+
+**Daemon roadmap** *(scoped, on `next`)*
+
+- [ ] **Notification interception** — WeChat / Feishu / Slack / WhatsApp / iMessage. Surface what matters, suppress noise, draft replies before you ask.
+- [ ] **Routine automation** — subscribed feeds, blogs, daily digests, alarms, calendar. Fires without you opening anything.
+- [ ] **State-change watchers** — experiment finished, CPU/GPU spike, build green, someone @-pinged you. Push the moment, not the digest.
+
+---
+
+## License
+
+[Apache License 2.0](./LICENSE) — Yome Agent + official skills (`yome-skill-ppt`, `yome-skill-xl`, `yome-skill-cal`, `yome-skill-rem`, `yome-skill-fs`).
+
+Community-contributed skills published to the Yome hub are author-owned git repositories under their own license terms.
+
+---
+
+<div align="center">
+
+**YOME — Your Universal AI Work Buddy.**
+*Know everything. Run everywhere. Empower everyone.*
+
+</div>