@hasna/assistants 1.0.3 → 1.0.5

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2024-2026 Hasna
+Copyright (c) 2025 Hasna
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,520 +1,86 @@
-# @hasna/assistants
+# assistants
 
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+A general-purpose AI assistant designed to help with any task - from research and writing to coding, automation, and beyond. Built terminal-first with powerful integrations.
 
-A general-purpose AI assistant that runs in your terminal. Built with [Ink](https://github.com/vadimdemedes/ink) and powered by [Claude](https://www.anthropic.com/claude).
-
-**Not just for coding** - while it excels at development workflows, this assistant helps with research, writing, task management, automation, and any task you need assistance with.
-
-## Features
-
-- General-purpose assistant for any task
-- Interactive chat with Claude AI
-- Execute bash commands with approval
-- Read, write, and edit files
-- Fetch and search web content
-- Custom skills and hooks for domain-specific workflows
-- Project and plan management
-- Memory and context persistence across sessions
-- Session history and resumption
-- Identity management for different contexts
-- Voice input/output (optional)
-- Connectors for external services (Notion, Gmail, Linear, etc.)
+**This is not just a coding tool.** While it excels at development workflows, it's designed as a versatile assistant that can help with:
+- Research and analysis
+- Writing and content creation
+- Task management and productivity
+- Business operations
+- Personal assistance
+- Software development
+- Automation and integrations
 
 ## Installation
 
-### Prerequisites
-
-- [Bun](https://bun.sh) runtime (v1.0 or later)
-- [Anthropic API key](https://console.anthropic.com/)
-
-### Install globally
-
 ```bash
 bun add -g @hasna/assistants
 ```
 
-### Or run directly
-
-```bash
-bunx @hasna/assistants
-```
+**Requirements:**
+- [Bun](https://bun.sh) 1.0+
 
 ## Quick Start
 
-1. Set your Anthropic API key:
-
-```bash
-export ANTHROPIC_API_KEY="sk-ant-..."
-```
-
-2. Start the assistant:
-
 ```bash
-assistants
-# or use the short alias
-ast
-```
+# Set your API key (or add to ~/.secrets)
+export ANTHROPIC_API_KEY="your-key"
 
-3. Start chatting!
-
-## CLI Reference
-
-### Basic Usage
-
-```bash
-# Start interactive mode
+# Run
 assistants
-
-# Run in headless mode (non-interactive)
-assistants -p "What does this codebase do?"
 ```
 
-### Options
-
-| Option | Description |
-|--------|-------------|
-| `-h, --help` | Show help message |
-| `-v, --version` | Show version number |
-| `-p, --print <prompt>` | Run non-interactively with the given prompt |
-| `--output-format <format>` | Output format: `text` (default), `json`, `stream-json` |
-| `--allowed-tools <tools>` | Comma-separated tools to auto-approve |
-| `--system-prompt <prompt>` | Custom system prompt |
-| `--json-schema <schema>` | JSON Schema for structured output |
-| `-c, --continue` | Continue the most recent conversation |
-| `-r, --resume <session_id>` | Resume a specific session by ID |
-| `--cwd <path>` | Set working directory |
-
-### Headless Mode Examples
-
+Or add to `~/.secrets`:
 ```bash
-# Ask a question
-assistants -p "What does the auth module do?"
-
-# Run with JSON output
-assistants -p "Summarize this project" --output-format json
-
-# Stream JSON events
-assistants -p "Explain this code" --output-format stream-json
-
-# Auto-approve specific tools
-assistants -p "Fix the bug in auth.py" --allowed-tools "Read,Edit,Bash"
-
-# Get structured output with JSON Schema
-assistants -p "List all functions" --output-format json \
-  --json-schema '{"type":"array","items":{"type":"string"}}'
-
-# Continue a previous conversation
-assistants -p "What else can you tell me?" --continue
-
-# Resume a specific session
-assistants -p "Continue from where we left off" --resume abc123
+export ANTHROPIC_API_KEY="your-key"
 ```
 
-## Interactive Mode
-
-### Keyboard Shortcuts
-
-| Key | Action |
-|-----|--------|
-| `Enter` | Send message |
-| `Ctrl+C` | Stop current operation or exit |
-| `Ctrl+]` | Switch sessions |
-| `Up/Down` | Navigate command history |
-| `Tab` | Autocomplete commands |
-
-### Slash Commands
-
-| Command | Description |
-|---------|-------------|
-| `/help` | Show available commands |
-| `/exit` | Exit the assistant |
-| `/new` | Start a new session |
-| `/clear` | Clear the screen |
-| `/session` | Show current session info |
-| `/tokens` | Show token usage |
-| `/context` | Show/manage context window |
-| `/cost` | Show estimated cost |
-| `/status` | Show system status |
-| `/model` | Show/change model settings |
-| `/config` | Show/edit configuration |
-| `/init` | Initialize project settings |
-
-### Project & Plan Commands
-
-| Command | Description |
-|---------|-------------|
-| `/projects` | List and manage projects |
-| `/plans` | View and manage plans |
-| `/summarize` | Summarize the conversation |
-| `/compact` | Compact context to save tokens |
-
-### Scheduling Commands
-
-| Command | Description |
-|---------|-------------|
-| `/schedule` | Create a scheduled task |
-| `/schedules` | List scheduled tasks |
-| `/unschedule` | Remove a scheduled task |
-| `/pause` | Pause a schedule |
-| `/resume` | Resume a paused schedule |
-
-### Skills & Connectors
-
-| Command | Description |
-|---------|-------------|
-| `/skills` | List available skills |
-| `/skill <name>` | Execute a skill |
-| `/connectors` | List available connectors |
-
-### Hooks Commands
-
-| Command | Description |
-|---------|-------------|
-| `/hooks` | Open interactive hooks panel |
-| `/hooks list` | List all hooks (native + user) |
-| `/hooks enable <id>` | Enable a hook |
-| `/hooks disable <id>` | Disable a hook |
-| `/hooks test <id>` | Test a hook with sample input |
-| `/hooks help` | Show hooks help |
-
-### Advanced Commands
+## Features
 
-| Command | Description |
-|---------|-------------|
-| `/voice` | Toggle voice mode |
-| `/say <text>` | Speak text aloud |
-| `/listen` | Listen for voice input |
-| `/identity` | Manage agent identity |
-| `/whoami` | Show current identity |
-| `/assistant` | Configure assistant settings |
-| `/inbox` | Check email inbox |
-| `/wallet` | Manage crypto wallet |
-| `/secrets` | Manage secrets |
-| `/jobs` | View background jobs |
-| `/messages` | Agent-to-agent messages |
-| `/verification` | Manage verification sessions |
-| `/memory` | View memory usage |
-| `/rest` | Enter rest mode |
-| `/feedback` | Submit feedback |
-| `/security-log` | View security events |
+- **General-purpose**: Handles any task - research, writing, coding, automation, and more
+- **Terminal-first**: Fast, keyboard-driven interface with an Ink-based TUI
+- **Connector-powered**: Integrates with services via `connect-*` CLIs (Notion, Google Drive, Gmail, Linear, Slack, etc.)
+- **Skills**: Reusable instructions with `SKILL.md` files for domain-specific workflows
+- **Hooks**: Event-driven automation for custom behaviors
+- **Memory**: Persistent context across sessions for continuity
+- **Multi-session**: Work on multiple tasks simultaneously
+- **Identity management**: Switch between personas and contexts
 
 ## Configuration
 
-### Directory Structure
-
-```
-~/.assistants/
-├── config.json        # Global configuration
-├── sessions/          # Session history
-├── skills/            # Custom skills
-├── hooks.json         # Global hooks
-└── schedules/         # Scheduled tasks
-
-.assistants/           # Project-level (in any directory)
-├── config.json        # Project configuration
-├── skills/            # Project-specific skills
-└── hooks.json         # Project-specific hooks
-```
-
-### Configuration File
-
-Create `~/.assistants/config.json`:
+User config: `~/.assistants/config.json`
+Project config: `.assistants/config.json`
 
 ```json
 {
-  "model": "claude-sonnet-4-20250514",
-  "temperature": 0.7,
-  "maxTokens": 8192,
-  "connectors": ["notion", "googledrive"],
-  "voice": {
-    "tts": "elevenlabs",
-    "stt": "whisper"
-  }
+  "llm": {
+    "provider": "anthropic",
+    "model": "claude-opus-4-5"
+  },
+  "connectors": ["notion", "googledrive", "gmail", "linear", "slack"]
 }
 ```
 
-### Project Configuration
-
-Create `.assistants/config.json` in your project:
-
-```json
-{
-  "name": "My Project",
-  "description": "Project description",
-  "systemPrompt": "You are helping with a Node.js backend project.",
-  "context": [
-    "src/README.md",
-    "docs/architecture.md"
-  ]
-}
-```
-
-## Environment Variables
-
-| Variable | Required | Description |
-|----------|----------|-------------|
-| `ANTHROPIC_API_KEY` | Yes | Claude API access |
-| `ELEVENLABS_API_KEY` | No | ElevenLabs TTS |
-| `OPENAI_API_KEY` | No | Whisper STT |
-| `EXA_API_KEY` | No | Enhanced web search |
-| `AWS_ACCESS_KEY_ID` | No | AWS features |
-| `AWS_SECRET_ACCESS_KEY` | No | AWS features |
-| `AWS_REGION` | No | AWS region |
-| `ASSISTANTS_NO_SYNC` | No | Disable synchronized output (set to `1`) |
-
 ## Skills
 
-Skills are reusable prompts defined in `SKILL.md` files:
+Skills are `SKILL.md` files with YAML frontmatter:
 
-```markdown
+```yaml
 ---
-name: code-review
-description: Review code for issues and improvements
-argument-hint: <file-path>
-allowed-tools: Read, Grep
+name: daily-standup
+description: Generate daily standup
+allowed-tools: bash, googlecalendar, linear
 ---
 
-## Instructions
-
-Review the code at $ARGUMENTS and provide feedback on:
-1. Potential bugs
-2. Performance issues
-3. Code style
-4. Security concerns
+Generate a daily standup report for $ARGUMENTS
 ```
 
-Place in `~/.assistants/skills/code-review/SKILL.md` or `.assistants/skills/code-review/SKILL.md`.
-
-Use with `/skill code-review src/auth.ts` or `$code-review src/auth.ts`.
-
-## Hooks
+Invoke with `/skill-name`.
 
-Hooks intercept agent behavior at key lifecycle points. Use them to validate inputs, block dangerous actions, log activity, or inject context.
+## Documentation
 
-### Managing Hooks
-
-Use the interactive panel:
-```
-/hooks
-```
-
-Or manage via commands:
-```
-/hooks list           # List all hooks
-/hooks enable abc123  # Enable a hook by ID
-/hooks disable abc123 # Disable a hook
-/hooks test abc123    # Test a hook with sample input
-```
-
-### Hook Events
-
-| Event | When Triggered |
-|-------|----------------|
-| **PreToolUse** | Before any tool executes |
-| **PostToolUse** | After tool succeeds |
-| **PostToolUseFailure** | After tool fails |
-| **PermissionRequest** | When approval needed |
-| **UserPromptSubmit** | User sends message |
-| **SessionStart** | Session begins |
-| **SessionEnd** | Session ends |
-| **SubagentStart** | Subagent spawning |
-| **SubagentStop** | Subagent completes |
-| **PreCompact** | Before context compaction |
-| **Notification** | Notification sent |
-| **Stop** | Agent stopping |
-
-### Configuration
-
-Create `.assistants/hooks.json` in your project:
-
-```json
-{
-  "PreToolUse": [
-    {
-      "matcher": "Bash|Edit|Write",
-      "hooks": [
-        {
-          "id": "validate-commands",
-          "name": "Validate dangerous commands",
-          "description": "Blocks rm -rf, sudo, etc.",
-          "type": "command",
-          "command": "./scripts/validate.sh",
-          "timeout": 5000,
-          "enabled": true
-        }
-      ]
-    }
-  ],
-  "PostToolUse": [
-    {
-      "matcher": "Edit",
-      "hooks": [
-        {
-          "type": "command",
-          "command": "prettier --write \"$INPUT_file_path\"",
-          "async": true
-        }
-      ]
-    }
-  ]
-}
-```
-
-### Creating Hooks via Wizard
-
-Press `a` in the hooks panel to launch the interactive wizard:
-
-1. Select event type (PreToolUse, PostToolUse, etc.)
-2. Enter matcher pattern (regex or `*` for all)
-3. Choose hook type (command, prompt, agent)
-4. Enter command or prompt
-5. Set timeout and async options
-6. Choose save location (user, project, local)
-
-### Example: Block Dangerous Commands
-
-```bash
-#!/bin/bash
-# .assistants/scripts/validate.sh
-INPUT=$(cat)
-COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')
-
-if echo "$COMMAND" | grep -qE 'rm\s+-rf|sudo|shutdown'; then
-  echo "Blocked: dangerous command" >&2
-  exit 2  # Exit 2 = block
-fi
-
-exit 0  # Exit 0 = allow
-```
-
-### Native Hooks
-
-Built-in hooks that can be enabled/disabled:
-
-| Hook | Event | Description |
-|------|-------|-------------|
-| **scope-verification** | Stop | Verifies goals were met |
-
-Manage native hooks via `/hooks` panel or commands.
-
-## Programmatic Usage
-
-### EmbeddedClient (Full Control)
-
-```typescript
-import { EmbeddedClient } from '@hasna/assistants';
-
-// Create client with working directory
-const client = new EmbeddedClient(process.cwd(), {
-  systemPrompt: 'You are a helpful coding assistant.',
-  allowedTools: ['Read', 'Write', 'Edit', 'Bash'],
-});
-
-// Handle streaming chunks
-client.onChunk((chunk) => {
-  if (chunk.type === 'text' && chunk.content) {
-    process.stdout.write(chunk.content);
-  }
-});
-
-// Initialize and send a message
-await client.initialize();
-await client.send('What files are in this directory?');
-
-// Get session info
-console.log('Session ID:', client.getSessionId());
-console.log('Token usage:', client.getTokenUsage());
-
-// Cleanup
-client.disconnect();
-```
-
-### Headless Mode (Simple Queries)
-
-```typescript
-import { runHeadless } from '@hasna/assistants';
-
-// Run a simple query with JSON output
-await runHeadless({
-  prompt: 'Summarize this project in 3 bullet points',
-  cwd: process.cwd(),
-  outputFormat: 'json',
-});
-
-// Stream JSON events
-await runHeadless({
-  prompt: 'Explain the authentication system',
-  cwd: process.cwd(),
-  outputFormat: 'stream-json',
-});
-
-// Auto-approve tools
-await runHeadless({
-  prompt: 'Fix the bug in auth.ts',
-  cwd: process.cwd(),
-  outputFormat: 'text',
-  allowedTools: ['Read', 'Edit'],
-});
-```
-
-### Feature Detection
-
-```typescript
-import { getFeatureAvailability, getFeatureStatusMessage } from '@hasna/assistants';
-
-// Check what features are available
-const features = getFeatureAvailability();
-console.log('Core chat:', features.coreChat);     // true if ANTHROPIC_API_KEY set
-console.log('AWS features:', features.awsFeatures); // true if AWS configured
-
-// Get human-readable status
-console.log(getFeatureStatusMessage());
-```
-
-## Connectors
-
-Connectors integrate external services. Install separately:
-
-```bash
-# Example: Notion connector
-bun add -g @hasna/connect-notion
-
-# List available connectors
-assistants
-/connectors
-```
-
-## Troubleshooting
-
-### "ANTHROPIC_API_KEY not set"
-
-Set your API key:
-```bash
-export ANTHROPIC_API_KEY="sk-ant-..."
-```
-
-### Terminal rendering issues
-
-Try disabling synchronized output:
-```bash
-ASSISTANTS_NO_SYNC=1 assistants
-```
-
-### Slow startup
-
-The first run may take longer as dependencies are cached. Subsequent runs will be faster.
-
-### Session not found
-
-Sessions are stored in `~/.assistants/sessions/`. Use `/session` to see current session info.
+- [Admin Dashboard](./docs/ADMIN.md) - User management, audit logging, and system monitoring
 
 ## License
 
 MIT
-
-## See Also
-
-- [FEATURES.md](./FEATURES.md) - Detailed feature documentation
-- [Anthropic API Documentation](https://docs.anthropic.com/)
-- [Bun Documentation](https://bun.sh/docs)

package/dist/.assistants/ASSISTANTS.md

@@ -0,0 +1,10 @@
+You are Hasna Assistant, a non-coding assistant.
+
+Rules:
+- This is not a coding assistant. Do not modify project source files.
+- Only write helper scripts in `.assistants/scripts/<session-id>/`.
+- Prefer read-only tools (read, glob, grep) for inspection.
+- Use connector tools for external systems; do not run `connect-*` via shell.
+- Avoid destructive commands, installs, or environment changes.
+
+If code changes are needed, explain the fix or generate a helper script in the scripts folder and instruct the user how to apply it manually.

package/dist/.assistants/commands/reflect.md

@@ -0,0 +1,13 @@
+---
+name: reflect
+description: Reflect on the conversation and suggest next steps
+tags: [reflection, next-steps]
+---
+
+# Reflection
+
+Please summarize the last interaction and suggest 2-3 next steps.
+
+- Keep it concise
+- Focus on clarity
+- Ask a follow-up question if needed

package/dist/.assistants/feedback/1c552736-058b-4a60-a67b-f0e7ec228f6d.json

@@ -0,0 +1,8 @@
+{
+  "id": "1c552736-058b-4a60-a67b-f0e7ec228f6d",
+  "createdAt": "2026-02-03T18:28:49.763Z",
+  "type": "feedback",
+  "title": "Test feedback",
+  "description": "Something went wrong",
+  "source": "tool"
+}

package/dist/.assistants/feedback/324f7179-cb61-4591-803e-30877228610e.json

@@ -0,0 +1,11 @@
+{
+  "id": "324f7179-cb61-4591-803e-30877228610e",
+  "createdAt": "2026-02-04T08:48:37.530Z",
+  "type": "feedback",
+  "title": "Feedback",
+  "description": "Submitted via /feedback",
+  "source": "command",
+  "metadata": {
+    "cwd": "/Users/hasna/Workspace/hasna/opensource/opensourcedev/opensource-assistants"
+  }
+}

package/dist/.assistants/feedback/49077cdf-1097-40ee-9173-56bdd8e5740d.json

@@ -0,0 +1,8 @@
+{
+  "id": "49077cdf-1097-40ee-9173-56bdd8e5740d",
+  "createdAt": "2026-02-02T14:19:21.254Z",
+  "type": "feedback",
+  "title": "Test feedback",
+  "description": "Something went wrong",
+  "source": "tool"
+}

package/dist/.assistants/feedback/6937c140-58c0-480c-b579-bc31ee2924a6.json

@@ -0,0 +1,8 @@
+{
+  "id": "6937c140-58c0-480c-b579-bc31ee2924a6",
+  "createdAt": "2026-02-02T13:04:29.670Z",
+  "type": "feedback",
+  "title": "Test feedback",
+  "description": "Something went wrong",
+  "source": "tool"
+}

package/dist/.assistants/feedback/6c7c4eb1-9f23-49a4-8fa0-ff350550b038.json

@@ -0,0 +1,8 @@
+{
+  "id": "6c7c4eb1-9f23-49a4-8fa0-ff350550b038",
+  "createdAt": "2026-02-02T13:02:20.275Z",
+  "type": "feedback",
+  "title": "Test feedback",
+  "description": "Something went wrong",
+  "source": "tool"
+}

package/dist/.assistants/feedback/6ff5a208-3bc1-4a92-adb9-243d23c2e56f.json

@@ -0,0 +1,8 @@
+{
+  "id": "6ff5a208-3bc1-4a92-adb9-243d23c2e56f",
+  "createdAt": "2026-02-04T18:12:41.252Z",
+  "type": "feedback",
+  "title": "Test feedback",
+  "description": "Something went wrong",
+  "source": "tool"
+}

package/dist/.assistants/feedback/bf6c14e2-5264-4ecf-9858-05218e858546.json

@@ -0,0 +1,8 @@
+{
+  "id": "bf6c14e2-5264-4ecf-9858-05218e858546",
+  "createdAt": "2026-02-03T21:17:01.150Z",
+  "type": "feedback",
+  "title": "Test feedback",
+  "description": "Something went wrong",
+  "source": "tool"
+}

package/dist/.assistants/feedback/cf204917-529b-4cdb-a0a3-ff97033b59f4.json

@@ -0,0 +1,8 @@
+{
+  "id": "cf204917-529b-4cdb-a0a3-ff97033b59f4",
+  "createdAt": "2026-02-05T14:15:10.457Z",
+  "type": "feedback",
+  "title": "Test feedback",
+  "description": "Something went wrong",
+  "source": "tool"
+}

package/dist/.assistants/projects/11a6d12e-a46f-4a6c-bbe8-bc58ebf2eddc.json

@@ -0,0 +1,9 @@
+{
+  "id": "11a6d12e-a46f-4a6c-bbe8-bc58ebf2eddc",
+  "name": "default",
+  "description": "Default project for this folder",
+  "createdAt": 1770194959987,
+  "updatedAt": 1770194959987,
+  "context": [],
+  "plans": []
+}